Skip to Content
Servers and clients

Run a process server

Launch Streamsy routes as a long-running server on Bun, Node, or Deno, run background work in the same scope, and shut down cleanly.

A process server is one Effect main. Serve.layer serves the routes. The routes get their stream services from a storage Layer, and the listener binds the port. The runtime's runMain launches the whole Layer and stops it on a signal.

Bun

import { Layer, Schema } from "effect";
import { BunRuntime } from "@effect/platform-bun";
import { Http, Streamsy } from "@streamsy/core";
import { Serve } from "@streamsy/serve";
import { listener } from "@streamsy/serve/bun";
import { BunStorage } from "@streamsy/storage/bun";

export class Events extends Streamsy.json<Events>()("Game/Events", "events/:seat", {
  params: { seat: Schema.String },
  schema: Schema.String,
}) {}
export const game = Streamsy.group(Events);

export const App = Layer.mergeAll(
  Http.routes(game, { prefix: "/streams", access: "full" }),
  Serve.mount(Events, "/feed/:seat"),
);

const storage = BunStorage.layer(game, { client: { filename: "./data/streams.sqlite" } });

const Server = Serve.layer(App, { drainTimeout: "2 seconds" }).pipe(
  Layer.provide(storage),
  Layer.provide(listener({ port: 3000 })),
);

BunRuntime.runMain(Layer.launch(Server), { teardown: Serve.teardown });

Run it with bun main.ts. The server listens on 127.0.0.1:3000. A client creates events/1 with PUT /streams/events/1, appends with POST, and reads the feed with GET /feed/1. access: "full" lets any caller create and remove streams. Choose the access for each stream before you deploy. See Access. Stop the server with Ctrl-C, and the process exits 0.

Layer.launch builds Server and keeps it open until the main is interrupted. For the storage options, see Use SQLite.

Node

Add @effect/platform-node and @effect/sql-sqlite-node. The routes are the same. Only the runtime, the listener, and the storage Layer change:

import { Layer } from "effect";
import { NodeRuntime } from "@effect/platform-node";
import { SqliteClient } from "@effect/sql-sqlite-node";
import { Serve } from "@streamsy/serve";
import { listener } from "@streamsy/serve/node";
import { SqlStorage } from "@streamsy/storage";
import { App, game } from "./app.ts";

const storage = SqlStorage.layer(game).pipe(
  Layer.provide(SqlStorage.clientLayer(SqliteClient.make({ filename: "./data/streams.sqlite" }))),
);

const Server = Serve.layer(App).pipe(
  Layer.provide(storage),
  Layer.provide(listener({ port: 3000 })),
);

NodeRuntime.runMain(Layer.launch(Server), { teardown: Serve.teardown });

Move Events, game, and App from the Bun example into app.ts, and import them from there. Run the compiled main, or the TypeScript file with a loader, on a Node version that has node:sqlite.

Deno

Add @effect/platform-deno and @effect/sql-sqlite-node. Run nodeSqliteCompat before the SQLite client opens:

import { Effect, Layer } from "effect";
import { DenoRuntime } from "@effect/platform-deno";
import { SqliteClient } from "@effect/sql-sqlite-node";
import { Serve } from "@streamsy/serve";
import { listener, nodeSqliteCompat } from "@streamsy/serve/deno";
import { SqlStorage } from "@streamsy/storage";
import { App, game } from "./app.ts";

const client = SqlStorage.clientLayer(
  nodeSqliteCompat.pipe(Effect.andThen(SqliteClient.make({ filename: "./data/streams.sqlite" }))),
);

const Server = Serve.layer(App).pipe(
  Layer.provide(SqlStorage.layer(game).pipe(Layer.provide(client))),
  Layer.provide(listener({ port: 3000 })),
);

DenoRuntime.runMain(Layer.launch(Server), { teardown: Serve.teardown });

Run it with permissions for the network and the database file, for example deno run -A main.ts. See SQLite on Node and Deno.

Listener

Each runtime module exports a listener(options) Layer:

OptionDefaultRuntimesValue
port3000AllThe port
hostname127.0.0.1AllThe bind address. Use 0.0.0.0 to accept other hosts
gracefulShutdownTimeoutNoneAllA bound on the wait for in-flight requests at stop
idleTimeout0Bun0 keeps parked long polls open
server{}NodeThe options of createServer from node:http

The listener binds the port when its Layer builds. A bind failure, such as a port in use, fails the main with a ServeError. Before the routes attach and after they detach, the Node listener answers each request with 503 and Retry-After: 1. See the Bun, Node, and Deno listener references.

Background work

The launched Layer owns one scope. The listener, the storage, and every fiber that a Layer forks in that scope live until shutdown. Add background work as one more Layer:

import { Effect, Layer } from "effect";
import { Serve } from "@streamsy/serve";
import { listener } from "@streamsy/serve/bun";
import { BunStorage } from "@streamsy/storage/bun";
import { App, game } from "./app.ts";

declare const deliverForever: Effect.Effect<never>;

const storage = BunStorage.layer(game, { client: { filename: "./data/streams.sqlite" } });

const Background = Layer.effectDiscard(Effect.forkScoped(deliverForever));

const Server = Layer.mergeAll(Serve.layer(App), Background).pipe(
  Layer.provide(storage),
  Layer.provide(listener({ port: 3000 })),
);

deliverForever stands for an application background loop. The fiber runs beside the routes and shares their storage. Shutdown interrupts it. For effect projections with retries and deferred work, see Effects. For projections, see Attach and Follow. Projection.attach returns a Layer, so it goes beside Serve.layer in the same way.

Clean shutdown

On SIGINT or SIGTERM, runMain interrupts the main, and the scope closes in this order:

  1. Serve.layer signals every live read. A parked long poll answers 204 with its offset and cursor, as after a long-poll timeout. An SSE body ends after its last whole batch.
  2. The drain waits until no live read runs, or until drainTimeout passes. The default is 2 s. A live read that arrives in this window gets the same reply at once.
  3. The serve Layer closes and interrupts the handlers that still run.
  4. In the Bun example, the storage closes, then the listener stops.

Clients take their normal reconnect path after step 1, so a restart loses no data.

ExitCode with Serve.teardown
Interrupted by SIGINT or SIGTERM0
Success0
Failure, such as a port in useNot 0 (1 by default)

Without Serve.teardown, runMain exits 130 after a signal. Serve.teardown maps every exit that holds only interrupts to 0, and leaves other exits to the default teardown. Use it with a main that ends only by failure or signal, such as Layer.launch.

Serve.layer(routes, options) takes the options of HttpRouter.serve, plus drainTimeout. A host with no stop signal, such as a Durable Object, uses HttpRouter.toWebHandler and neither Serve.layer nor Serve.teardown. See Run on Cloudflare.

Timeouts

Live reads keep a request open. A long poll parks for the storage Layer's longPollTimeoutMs, 30 s by default, and then answers 204. An SSE response lasts sseDeadlineMs, 60 s by default, and the client reconnects.

RuntimeLive reads
BunKeep idleTimeout at 0, the default. Bun otherwise closes an idle connection after 10 s
NodeThe node:http defaults hold live reads. requestTimeout bounds only the time to receive a request
DenoDeno.serve has no response timeout

A proxy or load balancer in front of the server needs an idle timeout above both values, and it must not buffer SSE responses. A client abort interrupts a parked long poll and releases its subscription.

Hosts

RuntimeMainListenerSQLite storageProcesses for each file
BunBunRuntime.runMain@streamsy/serve/bunBunStorage.layerSeveral
NodeNodeRuntime.runMain@streamsy/serve/nodeSqlStorage.layer over @effect/sql-sqlite-nodeOne
DenoDenoRuntime.runMain@streamsy/serve/denoAs Node, after nodeSqliteCompatOne

On every process host, expired streams are removed when a call reaches them. A process host runs no expiry sweep. An application can sweep with Protocol.expireDue(). A commit wakes followers in the same process at once, and followers in another process on the same file within repairIntervalMs. See Several processes.

This guide covers the process. Backups, replication, TLS, and high availability belong to your deployment.

On this page