Add telnet server

Dockerfile

@@ -4,5 +4,6 @@ WORKDIR /app
 COPY . .
 RUN pip install --no-cache-dir -r requirements.txt
 EXPOSE 8080
+EXPOSE 7373
 
 CMD ["python3", "spothole.py"]

config-example.yml

@@ -17,6 +17,12 @@ api_only_mode: false
 # The base URL at which the software runs.
 base_url: "http://localhost:8080"
 
+# Whether to run a telnet spot server as well as the web interface
+telnet_server_enabled: false
+
+# Port to run the telnet server on
+telnet_server_port: 7373
+
 # Spot providers to use. This is an example set, tailor it to your liking by commenting and uncommenting.
 # RBN and APRS-IS are supported but have such a high data rate, you probably don't want them enabled.
 # Each provider needs a class and an enabled/disabled state. Some require more config such as hostnames/IP

core/config.py

@@ -24,6 +24,8 @@ MAX_SPOT_AGE = config.get("max_spot_age_sec", 3600)
 MAX_ALERT_AGE = config.get("max_alert_age_sec", 604800)
 SERVER_OWNER_CALLSIGN = config.get("server_owner_callsign", "N0CALL")
 WEB_SERVER_PORT = config.get("web_server_port", 8080)
+TELNET_SERVER_ENABLED = config.get("telnet_server_enabled", False)
+TELNET_SERVER_PORT = config.get("telnet_server_port", 7373)
 ALLOW_SPOTTING = config.get("allow_spotting", True)
 ALLOW_UPSTREAM_SPOTTING = config.get("allow_upstream_spotting", True)
 WEB_UI_OPTIONS = config.get("web_ui_options", {})

core/status_reporter.py

@@ -11,7 +11,7 @@ from core.constants import SOFTWARE_VERSION
 from core.data_providers import DATA_PROVIDERS
 from core.data_store import DATA_STORE
 from core.prometheus_metrics_handler import alerts_gauge, memory_use_gauge, spots_gauge
-from server.webserver import WEB_SERVER
+from webserver.webserver import WEB_SERVER
 
 
 class StatusReporter:

docs/docker.md

@@ -13,6 +13,7 @@ services:
     restart: unless-stopped
     ports:
       - "8080:8080"
+      - "7373:7373" # For telnet if required
     volumes:
       - ./config.yml:/app/config.yml
       - ./cache:/app/cache

docs/modifying.md

@@ -16,9 +16,12 @@ To navigate your way around the source code, this list may help.
 * `/providers/solarconditions` - Classes providing solar and propagation by accessing the APIs of other services
 * `/providers/staticdata` - Classes providing static lookup data by accessing bundled data files or the APIs of other
   services
+* `/providers/callsign` - Classes providing callsign lookup data by accessing bundled data files or the APIs of other
+  services
 * `/providers/sigrefdata` - Classes providing SIG reference lookup data by accessing bundled data files or the APIs of
   other services
-* `/server` - Classes for running Spothole's own web server
+* `/webserver` - Classes for running Spothole's own web server
+* `/telnetserver` - Classes for running Spothole's telnet server
 * `spothole.py` - Main application script
 
 *Templates*

spothole.py

@@ -5,12 +5,13 @@ import signal
 import sys
 
 from core.cleanup import CLEANUP_TIMER
-from core.config import LOG_LEVEL, SERVER_OWNER_CALLSIGN
+from core.config import LOG_LEVEL, SERVER_OWNER_CALLSIGN, TELNET_SERVER_ENABLED, TELNET_SERVER_PORT
 from core.constants import SOFTWARE_VERSION
 from core.data_providers import DATA_PROVIDERS
 from core.data_store import DATA_STORE
 from core.status_reporter import StatusReporter
-from server.webserver import WEB_SERVER
+from telnetserver.telnetserver import TELNET_SERVER
+from webserver.webserver import WEB_SERVER
 
 logger = logging.getLogger(__name__)
 
@@ -20,6 +21,7 @@ def shutdown(_signum=None, _frame=None):
 
     logger.info("Stopping program...")
     WEB_SERVER.stop()
+    TELNET_SERVER.stop()
     DATA_PROVIDERS.stop()
     CLEANUP_TIMER.stop()
     DATA_STORE.close()
@@ -60,6 +62,10 @@ if __name__ == "__main__":
     # Set up the web server
     WEB_SERVER.setup()
 
+    # Run the telnet server
+    if TELNET_SERVER_ENABLED:
+        TELNET_SERVER.start(port=TELNET_SERVER_PORT)
+
     # Run the web server. This is the blocking call that keeps the application running in the main thread, so this must
     # be the last thing we do. web_server.stop() triggers an await condition in the web server which finishes the main
     # thread.

telnetserver/telnetserver.py

@@ -0,0 +1,168 @@
+import asyncio
+import logging
+import threading
+from datetime import datetime
+
+import pytz
+
+from core.config import SERVER_OWNER_CALLSIGN
+from core.constants import SOFTWARE_VERSION
+from core.data_store import DATA_STORE
+from data.spot import Spot
+
+logger = logging.getLogger(__name__)
+
+
+class TelnetServer:
+    """A telnet server designed to provide spots in the same format as DXSpider, for compatibility with desktop loggers."""
+
+    def __init__(self):
+        self._port = None
+        self._running = False
+        self._clients = set()
+        self._loop = None
+
+    def start(self, port=7373):
+        """Starts the telnet server"""
+
+        self._port = port
+
+        # Start telnet server on the async loop
+        def run_loop():
+            self._loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self._loop)
+            self._loop.run_until_complete(self._start_internal())
+            self._loop.run_forever()
+
+        # Start the network thread as a daemon so it exits cleanly when the main script stops
+        t = threading.Thread(target=run_loop, daemon=True)
+        t.start()
+        logger.debug("Telnet server background thread spawned")
+
+        # Listen for new spots and alerts being added to the cache, so we can notify SSE clients immediately
+        DATA_STORE.spots.add_listener(self.publish)
+        self._running = True
+
+    async def _start_internal(self):
+        logger.info(f"Telnet server listening on port {self._port}")
+        await asyncio.start_server(self._handle_client, "0.0.0.0", self._port)
+
+    async def _handle_client(self, reader, writer):
+        """Handles a new client connection"""
+
+        logger.debug("Telnet client connected")
+        self._clients.add(writer)
+
+        # Print MOTD
+        try:
+            motd = (
+                f"Welcome to Spothole v{SOFTWARE_VERSION}.\r\nThis server is run by {SERVER_OWNER_CALLSIGN}.\r\n===\r\n"
+            )
+            writer.write(motd.encode("ascii"))
+            await writer.drain()
+        except Exception:
+            pass
+
+        # Set up buffer for user input
+        input_buffer = ""
+
+        try:
+            # Read forever, picking out any commands. Currently we just support "exit"
+            while True:
+                data = await reader.read(1024)
+                if not data:
+                    break
+
+                text = data.decode("ascii", errors="ignore")
+
+                for char in text:
+                    if char in ("\r", "\n"):
+                        # User pressed Enter, evaluate the command
+                        command = input_buffer.strip().lower()
+                        input_buffer = ""
+
+                        if command == "exit":
+                            writer.write(b"Goodbye!\r\n")
+                            await writer.drain()
+                            # Exit the while read loop, this will disconnect the client.
+                            return
+
+                    elif char in ("\b", "\x7f"):
+                        # Handle backspaces
+                        input_buffer = input_buffer[:-1]
+                    else:
+                        input_buffer += char
+
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            logger.exception("Exception handling telnet client")
+        finally:
+            logger.debug("Telnet client disconnected")
+            self._clients.remove(writer)
+            writer.close()
+            await writer.wait_closed()
+
+    def stop(self):
+        """Stops the telnet server"""
+
+        if self._loop and self._loop.is_running():
+            logger.debug("Stopping telnet server...")
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+    async def _stop_internal(self):
+        """Stops the telnet server"""
+
+        for writer in list(self._clients):
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+        self._clients.clear()
+
+    def publish(self, spot: Spot):
+        """Callback from the data store when a spot is added"""
+
+        if self._running and self._clients and self._loop and self._loop.is_running():
+            asyncio.run_coroutine_threadsafe(self._broadcast_spot_internal(spot), self._loop)
+
+    async def _broadcast_spot_internal(self, spot: Spot):
+        """Internal version, run on async loop for thread safety?"""
+
+        # Ensure ASCII formatting for telnet clients
+        encoded_line = self._format_dxspider_spot(spot).encode("ascii", errors="ignore")
+
+        # Try to write to all clients, and in the process find the ones that are disconnected
+        disconnected_clients = set()
+        for writer in self._clients:
+            try:
+                writer.write(encoded_line)
+                await writer.drain()
+            except Exception:
+                disconnected_clients.add(writer)
+
+        # Clean up any disconnected connections caught during writing
+        for writer in disconnected_clients:
+            self._clients.discard(writer)
+
+    @staticmethod
+    def _format_dxspider_spot(spot: Spot) -> str:
+        """Formats a spot into the format DXspider uses:
+        DX de CALLSIGN:  FREQUENCY  DX_CALLSIGN  COMMENTS   TIME_UTC"""
+
+        de_call = f"{spot.de_call + ':' if spot.de_call else '???:'!s:<9}"
+        frequency = f"{(spot.freq / 1000.0):8.1f}"
+        dx_call = f"{spot.dx_call!s:<12}"
+        comment = f"{spot.comment[:29]:<30}"
+        if spot.time:
+            timestamp = datetime.fromtimestamp(spot.time, tz=pytz.utc).strftime("%H%M") + "Z"
+        else:
+            timestamp = datetime.now(tz=pytz.utc).strftime("%H%M") + "Z"
+
+        # Combine into classic DXSpider output string followed by network line breaks
+        return f"DX de {de_call} {frequency}  {dx_call} {comment} {timestamp}\r\n"
+
+
+# Global object
+TELNET_SERVER = TelnetServer()

templates/add_spot.html

@@ -77,7 +77,7 @@
 
 </div>
 
-<script src="/static/js/add-spot.js?v=1789134214"></script>
+<script src="/static/js/add-spot.js?v=1789138557"></script>
 <script>$(document).ready(function () {
     $("#nav-link-add-spot").addClass("active");
 }); <!-- highlight active page in nav --></script>

templates/alerts.html

@@ -83,7 +83,7 @@
 
 </div>
 
-<script src="/static/js/alerts.js?v=1789134214"></script>
+<script src="/static/js/alerts.js?v=1789138557"></script>
 <script>$(document).ready(function () {
     $("#nav-link-alerts").addClass("active");
 }); <!-- highlight active page in nav --></script>

templates/bands.html

@@ -76,8 +76,8 @@
 
 </div>
 
-<script src="/static/js/spotsbandsandmap.js?v=1789134214"></script>
-<script src="/static/js/bands.js?v=1789134214"></script>
+<script src="/static/js/spotsbandsandmap.js?v=1789138557"></script>
+<script src="/static/js/bands.js?v=1789138557"></script>
 <script>$(document).ready(function () {
     $("#nav-link-bands").addClass("active");
 }); <!-- highlight active page in nav --></script>

templates/base.html

@@ -1,6 +1,6 @@
 {% extends "skeleton.html" %}
 {% block head_extra %}
-<link rel="stylesheet" href="/static/css/style.css?v=1789134213" type="text/css">
+<link rel="stylesheet" href="/static/css/style.css?v=1789138557" type="text/css">
 <link href="/static/vendor/css/bootstrap-5.3.8.min.css" rel="stylesheet">
 <link href="/static/vendor/css/fontawesome-6.7.2.min.css" rel="stylesheet">
 <link href="/static/vendor/css/solid-6.7.2.min.css" rel="stylesheet">
@@ -16,10 +16,10 @@
     window.fetchEventSource = fetchEventSource;
 </script>
 
-<script src="/static/js/utils.js?v=1789134213"></script>
-<script src="/static/js/ui-ham.js?v=1789134213"></script>
-<script src="/static/js/geo.js?v=1789134213"></script>
-<script src="/static/js/common.js?v=1789134213"></script>
+<script src="/static/js/utils.js?v=1789138557"></script>
+<script src="/static/js/ui-ham.js?v=1789138557"></script>
+<script src="/static/js/geo.js?v=1789138557"></script>
+<script src="/static/js/common.js?v=1789138557"></script>
 {% end %}
 {% block body %}
 <div class="container">

templates/conditions.html

@@ -284,7 +284,7 @@
 </div>
 
 <script src="/static/vendor/js/chart-4.4.9.umd.min.js"></script>
-<script src="/static/js/conditions.js?v=1789134214"></script>
+<script src="/static/js/conditions.js?v=1789138557"></script>
 <script>$(document).ready(function () {
     $("#nav-link-conditions").addClass("active");
 }); <!-- highlight active page in nav --></script>

templates/map.html

@@ -113,8 +113,8 @@
     const CARTODB_API_KEY = "{{ web_ui_options.get('cartodb_api_key', '') }}";
 </script>
 
-<script src="/static/js/spotsbandsandmap.js?v=1789134214"></script>
-<script src="/static/js/map.js?v=1789134214"></script>
+<script src="/static/js/spotsbandsandmap.js?v=1789138557"></script>
+<script src="/static/js/map.js?v=1789138557"></script>
 <script>$(document).ready(function () {
     $("#nav-link-map").addClass("active");
 }); <!-- highlight active page in nav --></script>

templates/spots.html

@@ -113,8 +113,8 @@
 
 </div>
 
-<script src="/static/js/spotsbandsandmap.js?v=1789134213"></script>
-<script src="/static/js/spots.js?v=1789134213"></script>
+<script src="/static/js/spotsbandsandmap.js?v=1789138557"></script>
+<script src="/static/js/spots.js?v=1789138557"></script>
 <script>$(document).ready(function () {
     $("#nav-link-spots").addClass("active");
 }); <!-- highlight active page in nav --></script>

templates/status.html

@@ -86,7 +86,7 @@
     </div>
 </div>
 
-<script src="/static/js/status.js?v=1789134214"></script>
+<script src="/static/js/status.js?v=1789138557"></script>
 <script>
     $(document).ready(function () {
         $("#nav-link-status").addClass("active");

webserver/handlers/api/v1_spots.py

@@ -1,6 +1,6 @@
 import re
 
-from server.handlers.api.spots import APISpotsHandler, APISpotsStreamHandler
+from webserver.handlers.api.spots import APISpotsHandler, APISpotsStreamHandler
 
 _GRID_SOURCE_RE = re.compile(r'"dx_location_source":\s*"GRID"')
 _LEGACY_PARAM_TO_HEADER_MAP = {

webserver/webserver.py

@@ -14,25 +14,25 @@ from core.config import (
 )
 from core.data_providers import DATA_PROVIDERS
 from core.data_store import DATA_STORE
-from server.handlers.api.addspot import APISpotHandler
-from server.handlers.api.alerts import APIAlertsHandler, APIAlertsStreamHandler
-from server.handlers.api.dxstats import APIDxStatsHandler
-from server.handlers.api.lookups import (
+from webserver.handlers.api.addspot import APISpotHandler
+from webserver.handlers.api.alerts import APIAlertsHandler, APIAlertsStreamHandler
+from webserver.handlers.api.dxstats import APIDxStatsHandler
+from webserver.handlers.api.lookups import (
     APILookupCallHandler,
     APILookupGridHandler,
     APILookupSIGRefHandler,
 )
-from server.handlers.api.options import APIOptionsHandler
-from server.handlers.api.solar_conditions import APISolarConditionsHandler
-from server.handlers.api.spots import APISpotsHandler, APISpotsStreamHandler
-from server.handlers.api.status import APIStatusHandler
-from server.handlers.api.v1_addspot import V1APISpotHandler
-from server.handlers.api.v1_compatability import V1RedirectHandler
-from server.handlers.api.v1_spots import V1APISpotsHandler, V1APISpotsStreamHandler
-from server.handlers.manifesthandler import ManifestHandler
-from server.handlers.metrics import PrometheusMetricsHandler
-from server.handlers.pagetemplate import PageTemplateHandler
-from server.sse_broadcaster import SSEBroadcaster
+from webserver.handlers.api.options import APIOptionsHandler
+from webserver.handlers.api.solar_conditions import APISolarConditionsHandler
+from webserver.handlers.api.spots import APISpotsHandler, APISpotsStreamHandler
+from webserver.handlers.api.status import APIStatusHandler
+from webserver.handlers.api.v1_addspot import V1APISpotHandler
+from webserver.handlers.api.v1_compatability import V1RedirectHandler
+from webserver.handlers.api.v1_spots import V1APISpotsHandler, V1APISpotsStreamHandler
+from webserver.handlers.manifesthandler import ManifestHandler
+from webserver.handlers.metrics import PrometheusMetricsHandler
+from webserver.handlers.pagetemplate import PageTemplateHandler
+from webserver.sse_broadcaster import SSEBroadcaster
 
 logger = logging.getLogger(__name__)