What Protocols Does the Railway Relay Use for Persistent Data Connections in WorldMonitor?

The Railway relay in koala73/worldmonitor uses WebSocket for AIS vessel tracking, HTTPS REST with OAuth2 for OpenSky aircraft data, and MTProto over TCP/TLS for Telegram OSINT feeds.

The koala73/worldmonitor repository implements a multi-protocol relay system designed to aggregate real-time intelligence from maritime, aviation, and open-source intelligence (OSINT) sources. Understanding what protocols the Railway relay uses for persistent data connections is essential for developers deploying or extending this monitoring infrastructure.

AIS Vessel Tracking: WebSocket Protocol

The relay maintains a single long-lived WebSocket connection to stream real-time Automatic Identification System (AIS) vessel positions.

Implementation in ais-relay.cjs

In scripts/ais-relay.cjs, the relay opens a persistent WebSocket to aisstream.io and keeps it alive for the lifetime of the process:

// scripts/ais-relay.cjs - lines 32-34
const AISSTREAM_URL = 'wss://stream.aisstream.io/v0/stream';

// The WebSocket connection remains open indefinitely
const ws = new WebSocket(AISSTREAM_URL, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});

All downstream clients receive fresh JSON snapshots via HTTP endpoints (/ais-snapshot) that read from an in-memory state built from this WebSocket stream. This architecture minimizes latency for maritime tracking while reducing connection overhead.

OpenSky Aircraft Data: HTTPS REST with OAuth2

Unlike the AIS implementation, the OpenSky integration does not use a true persistent socket. Instead, it relies on HTTPS REST requests with OAuth2 bearer token authentication, reusing access tokens across repeated polling cycles.

Token-Based Authentication Flow

The relay authenticates via an OAuth2 client-credentials flow against the OpenSky identity provider:

// scripts/ais-relay.cjs - lines 462-468
const tokenRequest = {
  url: 'https://opensky-network.org/auth/realms/opensky-network/protocol/openid-connect/token',
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: `grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}`
};

After obtaining the bearer token, the relay repeatedly queries the aircraft states endpoint while the token remains valid:

// scripts/ais-relay.cjs - lines 4963-4965
const response = await fetch('https://opensky-network.org/api/states/all', {
  headers: { Authorization: `Bearer ${accessToken}` }
});

This approach implements a pseudo-persistent connection through token reuse and back-off loops, balancing real-time requirements with RESTful API constraints.

Telegram OSINT Feed: MTProto Protocol

For Telegram intelligence gathering, the relay implements MTProto, Telegram's proprietary TCP/TLS-based protocol, maintaining a persistent session through the telegram npm library.

Persistent TCP/TLS Session Management

The integration uses TelegramClient with StringSession to maintain authentication state across process restarts:

// scripts/ais-relay.cjs - lines 93-101
const { TelegramClient, StringSession } = require('telegram');
const { StoreSession } = require('telegram/sessions');

// Load existing session or create new
const session = new StringSession(process.env.TELEGRAM_SESSION || '');
const client = new TelegramClient(session, API_ID, API_HASH, {
  connectionRetries: 5,
  useWSS: false // Uses MTProto over TCP with TLS
});

The client maintains a persistent connection through a long-running polling loop:

// scripts/ais-relay.cjs - lines 106-108 and pollTelegramOnce loop
await client.connect();
setInterval(pollTelegramOnce, 30000); // Reuses same MTProto connection

This MTProto implementation provides encrypted, persistent access to Telegram channels and groups for OSINT monitoring without repeated authentication overhead.

OREF Siren Alerts: HTTPS via cURL

As an additional persistent data source, the relay handles OREF (Israeli Home Front Command) siren alerts using HTTPS via cURL rather than Node.js fetch. This implementation circumvents TLS fingerprinting blocks by using residential proxies:

// scripts/ais-relay.cjs - lines 93-100
const orefCurlFetch = (url) => {
  return execSync(`curl -x ${RESIDENTIAL_PROXY} -s "${url}"`, {
    encoding: 'utf8',
    timeout: 10000
  });
};

While these connections are short-lived per request, the proxy configuration maintains persistent routing through residential IP pools.

Summary

• AIS vessel tracking uses a persistent WebSocket connection to wss://stream.aisstream.io/v0/stream, maintained continuously in scripts/ais-relay.cjs.
• OpenSky aircraft data implements HTTPS REST with OAuth2 bearer tokens, reusing authentication across repeated polling cycles rather than maintaining a true persistent socket.
• Telegram OSINT feeds rely on the MTProto protocol over TCP/TLS, maintaining persistent sessions via TelegramClient and StringSession.
• OREF siren alerts use HTTPS via cURL through residential proxies to bypass TLS fingerprinting restrictions.

Frequently Asked Questions

Does the Railway relay use WebSocket for all data sources?

No, WebSocket is used only for AIS vessel tracking. OpenSky uses HTTPS REST with OAuth2, Telegram uses MTProto over TCP/TLS, and OREF uses HTTPS via cURL. Each protocol is chosen based on the specific requirements and constraints of the upstream data provider.

How does the relay maintain persistent connections to Telegram without re-authenticating?

The relay uses MTProto's StringSession mechanism, which serializes the authentication state to an environment variable (TELEGRAM_SESSION). When the process restarts, it loads this session string into TelegramClient, allowing it to resume the persistent TCP/TLS connection without requiring new authentication credentials.

Why does the OpenSky implementation use OAuth2 instead of a persistent WebSocket?

OpenSky's public API does not provide a WebSocket endpoint for aircraft states. The relay must poll the REST endpoint (/api/states/all) repeatedly using OAuth2 bearer tokens for authentication. While this creates higher overhead than a persistent socket, it is the only supported method for accessing OpenSky data programmatically.

What is the purpose of using cURL instead of Node.js fetch for OREF alerts?

The OREF (Israeli Home Front Command) servers implement TLS fingerprinting that blocks requests from Node.js's default TLS stack. By invoking curl through a residential proxy, the relay presents a standard browser TLS fingerprint, bypassing these restrictions and allowing successful HTTPS requests to the alert endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}