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.
| Option | Meaning |
|---|---|
readLimit | The largest number of messages in a catch-up page. A live read returns the whole tail. The default is 1000 |
longPollTimeoutMs | The 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.
| Member | Does |
|---|---|
head | Returns the metadata of the stream as a HeadResult |
read | Returns one catch-up page after options.offset |
readNext | Returns 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.
| Member | Does |
|---|---|
create | Creates the stream id, or forks it when options.forkedFrom is set |
fork | Creates the stream id as a fork of source. It is create with forkedFrom set to source |
append | Appends the encoded body in options.data as one request |
remove | Deletes 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.
RemoteStreams
Reference for the RemoteStreams namespace in @streamsy/core/remote. It provides stream services from a remote Durable Streams host over HTTP.
Streams
Reference for the Streams namespace in @streamsy/core/protocol. Its functions run the stream operations on a StreamAddress over the generic protocol reader and writer.