Aleph Networking Library

Aleph provides two distinct ways to interact with HTTP/2, allowing you to choose between standard Ring compatibility and low-level connection control:

1. Backwards-compatibility mode: This is the default mode. It uses the standard Ring API where your handler receives a single Ring map (with an InputStream body) and returns a Ring response map. In this mode, all streams have equal priority, and flow control uses a default Netty policy of a 64 kb window that auto-replenishes as bytes are read.

2. HTTP/2 connection mode: This mode provides a connection-level handler API. It allows you to access the entire connection, all streams within that connection, and all frames within those streams. This is intended for users who need fine-grained control over the HTTP/2 protocol.

When an HTTP request contains the appropriate Upgrade headers, you can upgrade the connection to a WebSocket by calling (aleph.http/websocket-connection req).

This returns a deferred that yields a duplex stream. This single stream represents bidirectional communication: you can receive messages from the client using take! and send messages to the client using put!. WebSocket text messages are emitted as strings, and binary messages are emitted as byte arrays.

(require '[manifold.stream :as s])

(defn echo-handler [req]
  (let [s @(http/websocket-connection req)]
    (s/connect s s))) ; Echoes all messages back to the client

When using Aleph's HTTP/2 capabilities, you can manage resource allocation and flow control through the following mechanisms:

• Flow Control: Aleph exposes APIs to get and set both stream-level and connection-level window sizes. In the default mode, the window size is 64 kb, but users can adjust the initial window size.
• Prioritization: Aleph provides APIs to get and set stream priorities and dependencies. Note that Aleph does not automatically act on this information; it is the responsibility of the user/developer to implement logic based on these priorities.
• Server Push: Aleph does not support HTTP/2 server push.

Aleph is fully Ring-compliant and can serve as a drop-in replacement for any Ring-compliant server. You can start a server by passing a handler function to aleph.http/start-server.

Your handler can return a standard Ring response map, or a Manifold deferred representing an eventual response. If you return a Manifold stream as the :body, Aleph will stream each message from the stream as a chunk, which is useful for Server-Sent Events (SSE).

(require '[aleph.http :as http])

(defn handler [req]
  {:status 200
   :headers {"content-type" "text/plain"}
   :body "hello!"})

(http/start-server handler {:port 8080})

You can install Aleph using Leiningen or deps.edn.

;; Leiningen
[aleph "0.9.10"]

;; deps.edn
aleph/aleph {:mvn/version "0.9.10"}
;; alternatively
io.github.clj-commons/aleph {:git/sha "..."}

To create a TCP server, provide a handler function to aleph.tcp/start-server. The handler function must accept two arguments:

1. A duplex stream (s) representing the connection.
2. A map (info) containing metadata about the client.

The stream emits byte-arrays and accepts messages that can be coerced into a binary representation. For advanced byte manipulation, it is recommended to use the byte-streams library.

Aleph's default scheduler uses ScheduledThreadPoolExecutor, which relies on blocking queues. This is inefficient for high-volume scheduling requests (exceeding 100k/sec). To optimize performance, you can provide a custom scheduler by redefining the manifold.time/*clock* var.

Your custom scheduler must implement the IClock protocol, which requires two functions:

1. in: Schedules a task to run once after a specified number of milliseconds.
2. every: Schedules a task to run repeatedly at a specified interval, starting after an initial delay.

To apply the new scheduler, use alter-var-root on #'manifold.time/*clock*.

The Aleph HTTP client is modeled after clj-http, but every request returns a Manifold deferred. You can use @ to wait for the response or d/chain for asynchronous composition. For HTTP/2 support, you must use a connection pool configured with the desired HTTP versions.

(require
  '[aleph.http :as http]
  '[manifold.deferred :as d]
  '[clj-commons.byte-streams :as bs])

;; Synchronous-style usage (blocking)
(-> @(http/get "https://google.com/")
    :body
    bs/to-string
    prn)

;; Asynchronous composition
(d/chain (http/get "https://google.com")
         :body
         bs/to-string
         prn)

;; HTTP/2 usage with connection pool
(def conn-pool
  (http/connection-pool {:connection-options {:http-versions [:http2 :http1]}}))
@(http/get "https://google.com" {:pool conn-pool})