Servers and clients
The pieces that expose stream services over HTTP, consume them from another program, and run the server.
A Streamsy server is three separate choices. The storage Layer provides the stream services. HTTP routes expose some of those services at URLs. A runtime owns the listener or the Worker entry point, the lifetime of the services, and background work. A client is a program that gets its stream services from a server instead of from local storage.
Application program → stream services → local storage Layer
or → RemoteStreams.layer → an existing server
HTTP request → Http.routes or Serve routes → stream services
Runtime → listener or Worker entry point + service lifetime + background workTwo server interfaces
| Interface | Package | Serves | Guide |
|---|---|---|---|
Http.routes(group, options) | @streamsy/core | The Durable Streams protocol for every stream in a group: create, append, read, and remove | Expose the stream protocol |
Serve.stream, Serve.state, Serve.value | @streamsy/serve | Read-only endpoints at application URLs: one stream, one Durable State change feed, or one computed value | Serve application reads |
Both are Effect HttpRouter route Layers. A server can merge both with Layer.mergeAll, and each needs the stream services of the streams that it reads. Neither creates a stream, runs a projection, or authenticates a caller.
Clients
| Client | Uses | Guide |
|---|---|---|
An Effect program with RemoteStreams.layer | The protocol routes | Connect to a remote server |
| A browser app with the Durable Streams client | The protocol routes | Browsers |
| A browser app that reads Serve endpoints | Serve routes | Browser clients and CORS |
A remote Effect program uses the same stream classes as the server, and its code does not change. A browser app does not load the server's Effect services. It reads the wire format through @durable-streams/client or @durable-streams/state.
Runtimes
| Runtime | Owns | Guide |
|---|---|---|
| Bun, Node, or Deno process | A listener, one scope for storage and background fibers, and a drain at shutdown | Run a process server |
| Cloudflare | A Worker router, and Durable Objects that each own their storage, routes, and alarm | Run on Cloudflare |
A process runs until a signal stops it, so it can keep a follow fiber or a delivery loop running. A Durable Object gets no stop signal and can be evicted between requests. It runs background work in alarm turns instead. See Schedule work with alarms.
The routes and the storage contract are the same on every runtime. Only the composition around them changes.
Pick a guide
| Task | Guide |
|---|---|
| Let protocol clients create, append, and read streams | Expose the stream protocol |
| Give a browser one feed, one state, or one value at an app URL | Serve application reads |
| Use another server's streams from an Effect program | Connect to a remote server |
| Start and stop a server on Bun, Node, or Deno | Run a process server |
| Run the routes in a Worker and Durable Objects | Run on Cloudflare |
| Run projections or deliveries with no request in flight on Cloudflare | Schedule work with alarms |
| Use a stream that another Durable Object owns | Connect Durable Objects |
| Choose where the data lives | Choose storage |
Write a storage adapter
Implement the Storage service for a new backend, bind streams to it, and check it with the contract tests and the protocol conformance suite.
Expose the stream protocol
Serve the Durable Streams protocol for a group of streams with Http.routes, choose the methods each stream allows, and protect the routes.