Skip to Content
Reference@streamsy/core

Protocol

Reference for the @streamsy/core/protocol entry point. It gives the generic protocol reader and writer, the Layer that builds them over Storage, and the raw HTTP route.

import {
  Protocol,
  StreamsReader,
  StreamsWriter,
  routes,
  type Reader,
  type Writer,
} from "@streamsy/core/protocol";
import type { Storage, StorageFault, StreamId, StreamsFault, Streamsy } from "@streamsy/core";
import type { Effect, Layer } from "effect";
import type { HttpRouter } from "effect/http";

The protocol tier reads and writes any stream id, with no codec and no stream class. Storage adapters, protocol tests, and HTTP internals use it. See Protocol tier.

This entry point also exports the Streams and StreamRoute namespaces. They are on the Streams and StreamRoute pages.

Layers

Protocol.layer

declare function layer(
  options?: Protocol.ProtocolOptions,
): Layer.Layer<StreamsReader | StreamsWriter, never, Storage>;

layer returns a Layer that builds the protocol reader and writer over the Storage service. It implements the Durable Streams rules on top of the store: offsets, expiry, closed streams, forks, and producer fencing. Provide a Storage Layer to it.

Building the Layer dies with a RangeError when longPollTimeoutMs is not a positive finite number, or when readLimit is not a positive safe integer.

Protocol.ProtocolOptions

interface ProtocolOptions {
  readonly readLimit?: number;
  readonly longPollTimeoutMs?: number;
}

ProtocolOptions holds the options of Protocol.layer.

OptionMeaning
readLimitThe largest number of messages in a catch-up page. A live read returns the whole tail. The default is 1000
longPollTimeoutMsThe longest wait of a long-poll read. The default is 30 s

Protocol.bind

declare function bind<A, E, R, const Keys extends ReadonlyArray<Streamsy.Any>>(
  graph: Layer.Layer<A | StreamsReader | StreamsWriter, E, R>,
  streams: Streamsy.Group<Keys>,
): Layer.Layer<Streamsy.Host<Streamsy.Group<Keys>>, E, R>;

bind returns a Layer with the service of each stream class in streams, over the reader and writer that graph provides. Each storage host builds its layer this way. See Bind streams.

import { Layer } from "effect";
import { MemoryStorage } from "@streamsy/core";
import { Protocol } from "@streamsy/core/protocol";
import { shop } from "./streams.ts";

const storage = Protocol.bind(MemoryStorage.layerProtocol(), shop);

bind throws a RangeError for the same groups as Streamsy.group, for example when two classes have the same name. When graph also provides Storage, that store must be the one under the reader and writer. Otherwise building the Layer dies with a RangeError.

Protocol.expireDue

declare const expireDue: () => Effect.Effect<void, StorageFault, Storage>;

expireDue returns an Effect that runs an expiry sweep. The sweep reads nextExpiry from the store, deletes that stream, and repeats until the next deadline is later than the clock. The host decides when to run a sweep, and it can interrupt one.

When a concurrent renewal or delete changes a stream first, the sweep skips that stream.

HTTP

routes

declare function routes(
  options?: Omit<Http.RoutesOptions, "access">,
): Layer.Layer<
  never,
  never,
  | HttpRouter.HttpRouter
  | HttpRouter.Request<"Requires", StreamsReader>
  | HttpRouter.Request<"Requires", StreamsWriter>
>;

routes returns an HttpRouter route Layer that serves the whole protocol for every id under prefix, over StreamsReader and StreamsWriter. It has no stream classes and no access rules, so every method is allowed. Adapters and the upstream conformance tests use routes. An application uses Http.routes.

options takes the options of Http.RoutesOptions except access. routes removes one trailing / from prefix. It throws a RangeError when prefix does not start with /, or contains ?, :, #, *, or //.

Services

StreamsReader

class StreamsReader extends Context.Service<StreamsReader, Reader<StreamsFault>>()(
  "@streamsy/core/StreamsReader",
) {}

StreamsReader is the service key of the generic protocol reader, and its service is a Reader that fails with a StreamsFault. Protocol.layer, MemoryStorage.layerProtocol, and RemoteStreams.layerProtocol provide it.

StreamsWriter

class StreamsWriter extends Context.Service<StreamsWriter, Writer<StreamsFault>>()(
  "@streamsy/core/StreamsWriter",
) {}

StreamsWriter is the service key of the generic protocol writer, and its service is a Writer that fails with a StreamsFault. The Layers that provide StreamsReader also provide StreamsWriter.

Reader

interface Reader<E = StorageFault> {
  readonly head: (id: StreamId) => Effect.Effect<HeadResult, HeadError | E>;
  readonly read: (id: StreamId, options?: ReadOptions) => Effect.Effect<ReadResult, ReadError | E>;
  readonly readNext: (
    id: StreamId,
    options: ReadNextOptions,
  ) => Effect.Effect<ReadNextResult, ReadNextError | E>;
}

Reader is the read side of the protocol, with the fault type E.

MemberDoes
headReturns the metadata of the stream as a HeadResult
readReturns one catch-up page after options.offset
readNextReturns the messages after options.offset. When there are none, it waits for new messages (long poll)

The options and results are on Options and results, and the errors are on Errors.

Writer

interface Writer<E = StorageFault> {
  readonly create: (
    id: StreamId,
    options?: CreateOptions,
  ) => Effect.Effect<CreateResult, CreateError | E>;
  readonly fork: (
    id: StreamId,
    source: StreamId,
    options?: Omit<CreateOptions, "forkedFrom">,
  ) => Effect.Effect<CreateResult, CreateError | E>;
  readonly append: (
    id: StreamId,
    options: AppendOptions,
  ) => Effect.Effect<AppendResult, AppendError | E>;
  readonly remove: (id: StreamId) => Effect.Effect<void, RemoveError | E>;
}

Writer is the write side of the protocol, with the fault type E.

MemberDoes
createCreates the stream id, or forks it when options.forkedFrom is set
forkCreates the stream id as a fork of source. It is create with forkedFrom set to source
appendAppends the encoded body in options.data as one request
removeDeletes the stream id

append takes the protocol AppendOptions, which carry the encoded body and its content type. A stream class builds them from its items.

On this page