Skip to Content
Reference@streamsy/core

RemoteStreams

Reference for the RemoteStreams namespace in @streamsy/core/remote. It provides stream services from a remote Durable Streams host over HTTP.

import { RemoteStreams } from "@streamsy/core/remote";
import type { Streamsy } from "@streamsy/core";
import type { StreamsReader, StreamsWriter } from "@streamsy/core/protocol";
import type { Layer } from "effect";
import type { HttpClient } from "effect/http";

RemoteStreams sends the stream operations to a remote Durable Streams host over HTTP, so a program that uses stream classes runs against the host with no change. The Layers need an Effect HttpClient. See Connect to a remote server.

RemoteStreams.layer

declare function layer<const Keys extends ReadonlyArray<Streamsy.Any>>(
  group: Streamsy.Group<Keys>,
  options: RemoteStreams.Options,
): Layer.Layer<
  Streamsy.Host<Streamsy.Group<Keys>>,
  RemoteStreams.TransportFault,
  HttpClient.HttpClient
>;

layer returns a Layer with the service of each stream class in group, over layerProtocol(options). It provides no Storage and no local change feed. For the host access that each operation needs and the limits for projections, see Connect to a remote server.

import { Layer } from "effect";
import { FetchHttpClient } from "effect/http";
import { RemoteStreams } from "@streamsy/core/remote";
import { shop } from "./streams.ts";

const remote = RemoteStreams.layer(shop, {
  baseUrl: "https://streams.example.com/streams",
}).pipe(Layer.provide(FetchHttpClient.layer));

layer throws a RangeError for the same groups as Streamsy.group.

RemoteStreams.layerProtocol

declare function layerProtocol(
  options: RemoteStreams.Options,
): Layer.Layer<StreamsReader | StreamsWriter, RemoteStreams.TransportFault, HttpClient.HttpClient>;

layerProtocol returns a Layer with the generic protocol reader and writer over HTTP, and no stream classes. Each operation sends its request to baseUrl followed by the stream id. Protocol tools use layerProtocol.

  • Building the Layer fails with a TransportFault whose reason is configuration when baseUrl is not an HTTP or HTTPS URL, or has a query, a fragment, or credentials.
  • An operation fails with a TransportFault whose reason is configuration when the stream id is not a canonical relative path, for example when it has an empty segment, .., %, ?, #, or \.
  • An operation fails with a TransportFault whose reason is request when the HTTP request fails.
  • A create or fork fails with InvalidCreateRequest before sending a request when both expiry options are set, or when DateTime.make cannot parse expiresAt. A ttlSeconds of 0 still counts as set.
  • An append with expectedOffset fails with NotSupported unless capabilities.expectedOffset is true. An append with producer fails with NotSupported unless capabilities.producer is true. The writer sends no request in these cases.

A create HTTP 400 response without stream-not-supported becomes InvalidCreateRequest for a plain create and InvalidForkRequest for a fork. A 400 response with stream-not-supported becomes NotSupported instead.

Each request has the headers of options.headers and cache-control: no-cache. The HttpClient and the calling fiber own the lifetime of each request, so an interrupted call cancels its request.

RemoteStreams.Options

interface Options {
  readonly baseUrl: string;
  readonly headers?: Readonly<Record<string, string>>;
  readonly capabilities?: {
    readonly expectedOffset?: boolean;
    readonly producer?: boolean;
  };
}

Options holds the options of layer and layerProtocol.

OptionMeaning
baseUrlThe protocol prefix of the host, for example https://host/streams
headersThe headers to send with each request, for example authorization
capabilities.expectedOffsettrue when the host supports Stream-Expected-Offset
capabilities.producertrue when the host supports the producer headers

The capabilities state what the host supports. The Layer does not discover them, and it does not infer them from a successful append.

RemoteStreams.TransportFault

type TransportFault = Core.TransportFault;
declare const TransportFault: typeof Core.TransportFault;

RemoteStreams.TransportFault is the root TransportFault class.

On this page