mles-rs

Mles

Mles (Modern Lightweight channEl Service) is a client-server data distribution protocol targeted to serve as a lightweight and reliable distributed publish-subscribe data service.

Please check https://mles.io and https://mles.io/blog.html for a generic overview of Mles and /c/mles for the latest news.

Mles v2 protocol overview

Mles clients connect to a Mles server using Mles protocol header first frame (uid, channel, optional auth) value triplet on a TLS [1] WebSocket [2] session where the triplet is encapsulated in JavaScript Object Notation (JSON). A Mles client first subscribes to a channel by sending the correct Mles protocol header first frame value triplet (uid, channel, optional auth) where the channel specifies the channel to publish/subscribe. The auth MAY be included in case authentication is needed on top of WebSocket TLS. A Mles client MUST set Sec-WebSocket-Protocol subprotocol to "mles-websocket" [3] to be able to establish a connection with a Mles server successfully.

The Mles server verifies the Mles protocol header first frame and then joins the Mles client to the selected channel. Every channel uses its own context and is independent of other channels: therefore a TLS session per (uid, channel) pair is always used. After joining, the Mles server distributes the value triplet between all clients on the same channel. If a Mles client wants to depart from a channel, it just closes the WebSocket TLS session. If a Mles client does not want to receive any message, it just closes the WebSocket TLS session receive side.

A Mles server MAY save the history of received data, which can be then distributed to new clients when they connect to the Mles server. In case Mles server is restarted, Mles peer server, or even a Mles client, MAY provide history data for the Mles server as a resynchronization for those channels for which it has the history available. This allows distributed data protection for the channel information. A client SHOULD implement packet deduplication to avoid showing duplicate messages to user.

An Mles proxy-client MAY proxy a selected channel data between several Mles servers. Mles servers see proxy sessions as any other Mles client sessions. A proxy MUST implement packet deduplication to avoid forwarding loops for several proxies on the same channel. This allows Mles proxy-client to share and distribute value triplet data in an organized and powerful, yet simple manner between several Mles servers.

Mles clients and servers are independent of IP version and do not use IP broadcast or multicast. A Mles server MAY be configured to use IP anycast.

Mles protocol details

The protocol header first frame for Mles is as follows:

{
	"uid":"<user identification>",
	"channel":"<selected channel>",
	"auth":"<optional authentication hash>"
}

Server usage

Usage: mles [OPTIONS] --domains <DOMAINS> --wwwroot <WWWROOT>

Options:
  -d, --domains <DOMAINS>
          Domain(s) - can be specified multiple times for multiple domains

  -e, --email <EMAIL>
          Contact info for Let's Encrypt certificate registration

  -c, --cache <CACHE>
          Cache directory for Let's Encrypt certificates

  -l, --limit <LIMIT>
          History limit - maximum number of messages to store per channel
          [default: 200]

  -f, --filelimit <FILELIMIT>
          Open files limit - maximum number of concurrent file handles
          [default: 256]

  -w, --wwwroot <WWWROOT>
          Www-root directory for domain(s)
          Structure: /path/static where domain example.io goes to static/example.io

  -s, --staging
          Use Let's Encrypt staging environment
          (see https://letsencrypt.org/docs/staging-environment/)

  -p, --port <PORT>
          TLS port for WebSocket connections
          [default: 443]

  -r, --redirect
          Enable HTTP to HTTPS redirect on port 80

  -C, --compression-cache <COMPRESSION_CACHE>
          Compression cache size in MB for static file serving
          Set to 0 to disable caching

      --rate-limit <RATE_LIMIT>
          Per-IP TCP-accept rate limit (connections/minute)
          Applies to the TLS port and (when --redirect is set) port 80.
          Connections from an IP exceeding the quota are dropped before TLS
          handshake. IPv4-mapped IPv6 addresses are normalized so a client
          counts as one IP regardless of socket family. Omit to disable.

  -h, --help
          Print help

Example server

• Acquire a public Internet server with a static IP + domain
• Open TLS port 443 in your firewall
• Ensure that your wwwroot-directory has the static web pages under it e.g. static/your.domain
• Run Mles server as root (due to port 443) with Let's Encrypt caching and debug logging enabled as shown below

RUST_LOG=debug mles --domains your.domain --cache . --wwwroot static

Multiple domains example

You can serve multiple domains by specifying the --domains flag multiple times:

RUST_LOG=debug mles \
  --domains your.domain \
  --domains www.your.domain \
  --cache . \
  --wwwroot static

With HTTP redirect and compression cache

Enable HTTP to HTTPS redirect and use a 100MB compression cache for better performance:

RUST_LOG=debug mles \
  --domains your.domain \
  --cache . \
  --wwwroot static \
  --redirect \
  --compression-cache 100

Production example with email contact

For production use, specify contact email for Let's Encrypt:

mles \
  --domains your.domain \
  --email admin@your.domain \
  --cache /var/cache/mles \
  --wwwroot /var/www \
  --redirect \
  --compression-cache 100 \
  --limit 500 \
  --filelimit 1024

With per-IP rate limiting

Cap each client IP at 120 new TCP connections per minute across both ports. Useful when fronting upstream services via --proxy, since abusive IPs are rejected at TCP accept before reaching the TLS handshake or any upstream:

mles \
  --domains your.domain \
  --email admin@your.domain \
  --cache /var/cache/mles \
  --wwwroot /var/www \
  --redirect \
  --rate-limit 120

Example clients

An example client session with websocat looks like this:

% websocat wss://mles.io --header "Sec-WebSocket-Protocol: mles-websocket"
{ "uid":"alice", "channel":"example" }
Hello Bob!

mles-client is another example. It also includes a proxy implementation which can be used to connect channels of several servers together in a distributed manner.

Existing client implementations over Mles (WebSocket) protocol

• MlesTalk in JavaScript
• mles-client
• <please ask to add your client here>

References

1. The Transport Layer Security (TLS) Protocol Version 1.3, https://tools.ietf.org/html/rfc8446
2. The WebSocket Protocol, https://tools.ietf.org/html/rfc6455
3. IANA registered Mles WebSocket Subprotocol, https://www.iana.org/assignments/websocket