Namespaces

Aleph exposes data from the network as a Manifold stream, which can easily be transformed into a java.io.InputStream, core.async channel, Clojure sequence, or many other byte representations. It exposes simple default wrappers for HTTP, TCP, and UDP, but allows access to full performance and flexibility of the underlying Netty library.

Aleph follows the Ring spec fully, and can be a drop-in replacement for any existing Ring-compliant server. However, it also allows for the handler function to return a Manifold deferred to represent an eventual response. This feature may not play nicely with Ring middleware which modifies the response, but this can be easily fixed by reimplementing the middleware using Manifold's let-flow operator.

The body of the response may also be a Manifold stream, where each message from the stream is sent as a chunk, allowing for precise control over streamed responses for server-sent events and other purposes.

On any HTTP request which has the proper Upgrade headers, you may call (aleph.http/websocket-connection req), which returns a deferred which yields a duplex stream, which uses a single stream to represent bidirectional communication. Messages from the client can be received via take!, and sent to the client via put!. An echo WebSocket handler, then, would just consist of:

This takes all messages from the client, and feeds them back into the duplex socket, returning them to the client. WebSocket text messages will be emitted as strings, and binary messages as byte arrays.

WebSocket clients can be created via (aleph.http/websocket-client url), which returns a deferred which yields a duplex stream that can send and receive messages from the server.

A TCP server is similar to an HTTP server, except that for each connection the handler takes two arguments: a duplex stream and a map containing information about the client. The stream will emit byte-arrays, which can be coerced into other byte representations using the byte-streams library. The stream will accept any messages which can be coerced into a binary representation.

A UDP socket can be generated using (aleph.udp/socket {:port 10001, :broadcast? false}). If the :port is specified, it will yield a duplex socket which can be used to send and receive messages, which are structured as maps with the following data:

{:host "example.com"
:port 10001
:message ...}

Where incoming packets will have a :message that is a byte-array, which can be coerced using byte-streams, and outgoing packets can be any data which can be coerced to a binary representation. If no :port is specified, the socket can only be used to send messages.