@streamsy/serve 0.0.0-stage → 0.4.0

package/dist/contract.js

@@ -0,0 +1,124 @@
+//#region src/contract.ts
+/** Encode a value with object keys sorted, recursively. Array order is preserved. */
+function canonicalJson(value) {
+	if (isCanonicalArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+	if (value === null) return "null";
+	if (value instanceof Object) return canonicalObject(value);
+	if (typeof value === "number" && !Number.isFinite(value)) throw new TypeError("Expected finite JSON number");
+	return JSON.stringify(value);
+}
+/**
+* A written predicate rather than a bare `Array.isArray` call, because only a
+* predicate narrows the non-array branch of this union to the record type.
+*/
+function isCanonicalArray(value) {
+	return Array.isArray(value);
+}
+function canonicalObject(value) {
+	const entries = [];
+	for (const key of Object.keys(value).toSorted(compareKeys)) {
+		const member = value[key];
+		if (member === void 0) continue;
+		entries.push(`${JSON.stringify(key)}:${canonicalJson(member)}`);
+	}
+	return `{${entries.join(",")}}`;
+}
+function compareKeys(left, right) {
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+}
+/** Eight lowercase hex characters of FNV-1a over the canonical encoding's UTF-16 code units. */
+function contractFingerprint(value) {
+	return hex(fnv1a(canonicalJson(value), 2166136261));
+}
+/**
+* Sixteen lowercase hex characters, as a strong entity tag body.
+*
+* Two FNV-1a passes with different offset bases are concatenated, because a
+* cache validator that collides serves a stale value: eight hex characters
+* are enough to notice that a contract changed, but not enough to key a
+* consumer's cache on.
+*/
+function valueEtag(canonical) {
+	return `"${hex(fnv1a(canonical, 2166136261))}${hex(fnv1a(canonical, 16777619))}"`;
+}
+function fnv1a(input, seed) {
+	let hash = seed;
+	for (let index = 0; index < input.length; index += 1) {
+		hash ^= input.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+}
+function hex(value) {
+	return value.toString(16).padStart(8, "0");
+}
+const STATE_VERSION_HEADER = "x-streamsy-state-version";
+const STATE_CONTRACT_HEADER = "x-streamsy-state-contract";
+const STREAM_VERSION_HEADER = "x-streamsy-stream-version";
+const STREAM_CONTRACT_HEADER = "x-streamsy-stream-contract";
+const VALUE_CONTRACT_HEADER = "x-streamsy-value-contract";
+const DURABLE_STATE_PROTOCOL = "https://durable-streams.dev/state-protocol/v1";
+const PUBLIC_ERROR_TAGS = [
+	"InvalidParams",
+	"ProtocolVersionUnsupported",
+	"ResumeRejected",
+	"ContractChanged",
+	"TransportUnavailable",
+	"WireEncodeFailed"
+];
+/** The browser's JSON error boundary; unknown fields are discarded. */
+function decodePublicError(value) {
+	if (value === null || !(value instanceof Object) || Array.isArray(value)) throw new TypeError("Expected error object");
+	const field = (key) => Object.getOwnPropertyDescriptor(value, key)?.value;
+	const string = (key) => {
+		const result = field(key);
+		if (typeof result !== "string") throw new TypeError(`Expected string ${key}`);
+		return result;
+	};
+	const _tag = string("_tag");
+	const route = string("route");
+	switch (_tag) {
+		case "InvalidParams": return {
+			_tag,
+			route,
+			parameter: string("parameter"),
+			detail: string("detail")
+		};
+		case "ProtocolVersionUnsupported":
+			if (field("supported") !== 1 || field("recovery") !== "replay-from-start") throw new TypeError("Invalid protocol recovery");
+			return {
+				_tag,
+				route,
+				supported: 1,
+				received: string("received"),
+				recovery: "replay-from-start"
+			};
+		case "ResumeRejected": {
+			const reason = field("reason");
+			if (reason !== "invalid-offset" && reason !== "history-unavailable" && reason !== "contract-changed" || field("recovery") !== "replay-from-start") throw new TypeError("Invalid resume recovery");
+			return {
+				_tag,
+				route,
+				reason,
+				recovery: "replay-from-start"
+			};
+		}
+		case "ContractChanged":
+			if (field("recovery") !== "refetch") throw new TypeError("Invalid refetch recovery");
+			return {
+				_tag,
+				route,
+				recovery: "refetch"
+			};
+		case "TransportUnavailable":
+		case "WireEncodeFailed": return {
+			_tag,
+			route,
+			detail: string("detail")
+		};
+		default: throw new TypeError("Unknown public error tag");
+	}
+}
+//#endregion
+export { DURABLE_STATE_PROTOCOL, PUBLIC_ERROR_TAGS, STATE_CONTRACT_HEADER, STATE_VERSION_HEADER, STREAM_CONTRACT_HEADER, STREAM_VERSION_HEADER, VALUE_CONTRACT_HEADER, canonicalJson, contractFingerprint, decodePublicError, valueEtag };

package/dist/deno.d.ts

@@ -0,0 +1,27 @@
+import { Duration, Effect } from "effect";
+//#region src/deno.d.ts
+export declare const DEFAULT_PORT = 3000;
+export declare const DEFAULT_HOSTNAME = "127.0.0.1";
+export interface ListenerOptions {
+  readonly port?: number;
+  readonly hostname?: string;
+  readonly gracefulShutdownTimeout?: Duration.Input;
+}
+/** The Deno listener for a Streamsy host. */
+export declare const listener: (options?: ListenerOptions) => import("effect/Layer").Layer<import("effect/http/Etag").Generator | import("effect/http/HttpPlatform").HttpPlatform | import("effect/http/HttpServer").HttpServer | import("@effect/platform-deno/DenoServices").DenoServices, import("effect/http/HttpServerError").ServeError, never>;
+/**
+ * Lets `@effect/sql-sqlite-node` open a database on Deno.
+ *
+ * The driver calls `enableLoadExtension(false)` on every open. Deno's
+ * `node:sqlite` `DatabaseSync` has no such method, so the open throws. This
+ * adds a no-op method when it is missing and leaves a runtime that has it
+ * alone. Run it before the first `SqliteClient.make`:
+ *
+ * ```ts
+ * const client = Deno.nodeSqliteCompat.pipe(
+ *   Effect.andThen(SqliteClient.make({ filename })),
+ * );
+ * ```
+ */
+export declare const nodeSqliteCompat: Effect.Effect<void>;
+//#endregion

package/dist/deno.js

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import { DenoHttpServer } from "@effect/platform-deno";
+//#region src/deno.ts
+const DEFAULT_PORT = 3e3;
+const DEFAULT_HOSTNAME = "127.0.0.1";
+const listenerOptions = (options) => ({
+	port: options.port ?? 3e3,
+	hostname: options.hostname ?? "127.0.0.1",
+	...options.gracefulShutdownTimeout === void 0 ? { disablePreemptiveShutdown: true } : { gracefulShutdownTimeout: options.gracefulShutdownTimeout }
+});
+/** The Deno listener for a Streamsy host. */
+const listener = (options = {}) => DenoHttpServer.layer(listenerOptions(options));
+/**
+* Lets `@effect/sql-sqlite-node` open a database on Deno.
+*
+* The driver calls `enableLoadExtension(false)` on every open. Deno's
+* `node:sqlite` `DatabaseSync` has no such method, so the open throws. This
+* adds a no-op method when it is missing and leaves a runtime that has it
+* alone. Run it before the first `SqliteClient.make`:
+*
+* ```ts
+* const client = Deno.nodeSqliteCompat.pipe(
+*   Effect.andThen(SqliteClient.make({ filename })),
+* );
+* ```
+*/
+const nodeSqliteCompat = Effect.promise(() => import("node:sqlite")).pipe(Effect.flatMap(({ DatabaseSync }) => Effect.sync(() => {
+	const prototype = DatabaseSync.prototype;
+	if (prototype.enableLoadExtension === void 0) prototype.enableLoadExtension = () => {};
+})));
+//#endregion
+export { DEFAULT_HOSTNAME, DEFAULT_PORT, listener, nodeSqliteCompat };

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+import { t as CanonicalValue } from "./contract-BUWJ-Sy2.js";
+import { Duration, Effect, Layer, Runtime, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerRespondable, HttpServerResponse } from "effect/http";
+import { Http, StreamAddress, Streamsy } from "@streamsy/core";
+import { StreamRoute } from "@streamsy/core/protocol";
+import { ShutdownSignal } from "@streamsy/core/http";
+//#region src/errors.d.ts
+/** The public error body. `cases` gives one validating constructor per tag. */
+export declare const PublicErrorSchema: Schema.TaggedUnion<{
+  readonly ContractChanged: Schema.TaggedStruct<"ContractChanged", {
+    readonly route: Schema.String;
+    readonly recovery: Schema.Literal<"refetch">;
+  }>;
+  readonly InvalidParams: Schema.TaggedStruct<"InvalidParams", {
+    readonly route: Schema.String;
+    readonly parameter: Schema.String;
+    readonly detail: Schema.String;
+  }>;
+  readonly ProtocolVersionUnsupported: Schema.TaggedStruct<"ProtocolVersionUnsupported", {
+    readonly route: Schema.String;
+    readonly supported: Schema.Literal<1>;
+    readonly received: Schema.String;
+    readonly recovery: Schema.Literal<"replay-from-start">;
+  }>;
+  readonly ResumeRejected: Schema.TaggedStruct<"ResumeRejected", {
+    readonly route: Schema.String;
+    readonly reason: Schema.Literals<readonly ["invalid-offset", "history-unavailable", "contract-changed"]>;
+    readonly recovery: Schema.Literal<"replay-from-start">;
+  }>;
+  readonly TransportUnavailable: Schema.TaggedStruct<"TransportUnavailable", {
+    readonly route: Schema.String;
+    readonly detail: Schema.String;
+  }>;
+  readonly WireEncodeFailed: Schema.TaggedStruct<"WireEncodeFailed", {
+    readonly route: Schema.String;
+    readonly detail: Schema.String;
+  }>;
+}>;
+declare const InvalidParams_base: Schema.Class<InvalidParams, Schema.TaggedStruct<"InvalidParams", {
+  readonly _tag: Schema.tag<"InvalidParams">;
+  readonly route: Schema.String;
+  readonly parameter: Schema.String;
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class InvalidParams extends InvalidParams_base {
+  responseHeaders: Readonly<Record<string, string>>;
+  [HttpServerRespondable.symbol](): Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+}
+declare const ProtocolVersionUnsupported_base: Schema.Class<ProtocolVersionUnsupported, Schema.TaggedStruct<"ProtocolVersionUnsupported", {
+  readonly _tag: Schema.tag<"ProtocolVersionUnsupported">;
+  readonly route: Schema.String;
+  readonly supported: Schema.Literal<1>;
+  readonly received: Schema.String;
+  readonly recovery: Schema.Literal<"replay-from-start">;
+}>, import("effect/Cause").YieldableError>;
+declare class ProtocolVersionUnsupported extends ProtocolVersionUnsupported_base {
+  responseHeaders: Readonly<Record<string, string>>;
+  [HttpServerRespondable.symbol](): Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+}
+declare const ResumeRejected_base: Schema.Class<ResumeRejected, Schema.TaggedStruct<"ResumeRejected", {
+  readonly _tag: Schema.tag<"ResumeRejected">;
+  readonly route: Schema.String;
+  readonly reason: Schema.Literals<readonly ["invalid-offset", "history-unavailable", "contract-changed"]>;
+  readonly recovery: Schema.Literal<"replay-from-start">;
+}>, import("effect/Cause").YieldableError>;
+declare class ResumeRejected extends ResumeRejected_base {
+  responseHeaders: Readonly<Record<string, string>>;
+  [HttpServerRespondable.symbol](): Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+}
+declare const ContractChanged_base: Schema.Class<ContractChanged, Schema.TaggedStruct<"ContractChanged", {
+  readonly _tag: Schema.tag<"ContractChanged">;
+  readonly route: Schema.String;
+  readonly recovery: Schema.Literal<"refetch">;
+}>, import("effect/Cause").YieldableError>;
+declare class ContractChanged extends ContractChanged_base {
+  responseHeaders: Readonly<Record<string, string>>;
+  [HttpServerRespondable.symbol](): Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+}
+declare const TransportUnavailable_base: Schema.Class<TransportUnavailable, Schema.TaggedStruct<"TransportUnavailable", {
+  readonly _tag: Schema.tag<"TransportUnavailable">;
+  readonly route: Schema.String;
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class TransportUnavailable extends TransportUnavailable_base {
+  responseHeaders: Readonly<Record<string, string>>;
+  [HttpServerRespondable.symbol](): Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+}
+declare const WireEncodeFailed_base: Schema.Class<WireEncodeFailed, Schema.TaggedStruct<"WireEncodeFailed", {
+  readonly _tag: Schema.tag<"WireEncodeFailed">;
+  readonly route: Schema.String;
+  readonly detail: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class WireEncodeFailed extends WireEncodeFailed_base {
+  responseHeaders: Readonly<Record<string, string>>;
+  [HttpServerRespondable.symbol](): Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+}
+type ServeError = InvalidParams | ProtocolVersionUnsupported | ResumeRejected | ContractChanged | TransportUnavailable | WireEncodeFailed;
+//#endregion
+//#region src/host.d.ts
+type DefaultServeRequires<R> = HttpRouter.Request.Only<"Requires", R> | HttpRouter.Request.Only<"GlobalRequires", R>;
+/** The options of `HttpRouter.serve`, plus the drain bound. */
+type LayerOptions<R = never, HE = never, HR = DefaultServeRequires<R>> = NonNullable<Parameters<typeof HttpRouter.serve<unknown, unknown, R, HE, HR>>[1]> & {
+  /** Upper bound on the wait for live reads to finish; default 2 seconds. */
+  readonly drainTimeout?: Duration.Input | undefined;
+};
+/**
+ * `HttpRouter.serve` with the Streamsy drain applied in the only correct place.
+ *
+ * Before the serve layer closes, the drain signals every live read: a parked
+ * long poll answers `204` with its offset and cursor, and an open SSE body ends
+ * after its last whole batch. It then waits until no live read is running, or
+ * `drainTimeout` passes. After that the serve layer interrupts any handler that
+ * is still running.
+ *
+ * The host provides storage, the listener and the Effect main:
+ *
+ * ```ts
+ * const Server = Serve.layer(routes).pipe(
+ *   Layer.provide(MemoryStorage.layer(streams)),
+ *   Layer.provide(listener()),
+ * );
+ * BunRuntime.runMain(Layer.launch(Server), { teardown: Serve.teardown });
+ * ```
+ */
+declare const layer: <A, E, R, HE = never, HR = DefaultServeRequires<R>>(routes: Layer.Layer<A, E, R>, options?: LayerOptions<R, HE, HR>) => Layer.Layer<A, HttpRouter.Request.Without<E>, import("effect/http/HttpServer").HttpServer | Exclude<Exclude<Exclude<HR, HttpRouter.GlobalProvided>, HttpRouter.HttpRouter>, ShutdownSignal> | Exclude<Exclude<HttpRouter.Request.Without<R>, HttpRouter.HttpRouter>, ShutdownSignal>>;
+/**
+ * Exit policy for a long-running Streamsy host after `Serve.layer` drains.
+ * Pass it to the runtime's `runMain` as `{ teardown: Serve.teardown }`.
+ *
+ * An exit that holds only interrupts maps to 0: after the drain, an interrupt
+ * from `SIGINT` or `SIGTERM` is the normal way for the server to stop. Every
+ * other exit uses `Runtime.defaultTeardown`, so a startup failure stays
+ * non-zero. Any interrupt-only exit maps to 0, including one that no signal
+ * caused. In a `Layer.launch` main the fiber ends only on failure or a signal.
+ */
+declare const teardown: Runtime.Teardown;
+declare namespace serve_d_exports {
+  export { ContractChanged, InvalidParams, LayerOptions, ProtocolVersionUnsupported, ReadOptions, ResumeRejected, ServeError, TransportUnavailable, ValueOptions, WireEncodeFailed, layer, mount, params, route, state, stream, teardown, value };
+}
+type Names<S extends string> = S extends `${string}:${infer N}/${infer Tail}` ? N | Names<Tail> : S extends `${string}:${infer N}` ? N : never;
+type ExactPath<Path extends string, P> = `/${string}` extends Path ? unknown : [Exclude<Names<Path>, keyof P>, Exclude<keyof P, Names<Path>>] extends [never, never] ? unknown : never;
+interface ReadOptions extends Http.ReadOptions {
+  readonly contract?: CanonicalValue;
+}
+/** Decode the matched route's parameters with the stream's codecs. */
+declare const params: <P>(declaration: {
+  readonly paramSchema: StreamRoute.PathSchema<P>;
+}) => Effect.Effect<P, InvalidParams, HttpRouter.RouteContext>;
+/** Own every method at this path, including beneath protocol wildcard routes. */
+declare function route<E, R>(path: HttpRouter.PathInput, handler: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>): import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request.From<"Error", E> | HttpRouter.Request.From<"Requires", Exclude<R, HttpRouter.Provided>>>;
+/** Mount one declared stream; state addresses select the Durable State contract. */
+declare function mount<P, A, K, RD, RE, const Path extends `/${string}`>(declaration: {
+  readonly paramSchema: StreamRoute.PathSchema<P>;
+  readonly at: (params: P) => Streamsy.Address<A, K, RD, RE>;
+}, path: Path & ExactPath<Path, NoInfer<P>>, options?: ReadOptions): import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", InvalidParams> | HttpRouter.Request<"Error", ProtocolVersionUnsupported> | HttpRouter.Request<"Error", ResumeRejected> | HttpRouter.Request<"Error", TransportUnavailable> | HttpRouter.Request<"Error", WireEncodeFailed> | HttpRouter.Request.From<"Requires", Exclude<K, HttpRouter.Provided>>>;
+/** Durable Streams response for one resolved address. */
+declare function stream<A, K, RD, RE>(address: Streamsy.Address<A, K, RD, RE>, options?: ReadOptions): Effect.Effect<HttpServerResponse.HttpServerResponse, ProtocolVersionUnsupported | ResumeRejected | TransportUnavailable | WireEncodeFailed, K | HttpServerRequest.HttpServerRequest | HttpRouter.RouteContext>;
+/** Durable State change response with replay-from-start recovery. */
+declare function state<C extends StreamAddress.Collections, K, RD, RE>(address: StreamAddress.StateAddress<C, RD, RE> & Streamsy.Address<StreamAddress.CollectionsChange<C>, K, RD, RE>, options?: ReadOptions): Effect.Effect<HttpServerResponse.HttpServerResponse, ProtocolVersionUnsupported | ResumeRejected | TransportUnavailable | WireEncodeFailed, K | HttpServerRequest.HttpServerRequest | HttpRouter.RouteContext>;
+interface ValueOptions {
+  readonly cache?: {
+    readonly visibility: "private" | "public";
+    readonly maxAgeSeconds: number;
+    readonly mustRevalidate: boolean;
+  };
+  readonly contract?: CanonicalValue;
+}
+/** Canonical JSON response for any computation, including mapped projection state. */
+declare const value: <A, I extends CanonicalValue, E, R, RE>(schema: Schema.Codec<A, I, never, RE>, compute: Effect.Effect<A, E, R>, options?: ValueOptions | undefined) => Effect.Effect<HttpServerResponse.HttpServerResponse, E | ContractChanged | WireEncodeFailed, R | RE | HttpServerRequest.HttpServerRequest | HttpRouter.RouteContext>;
+//#endregion
+export { serve_d_exports as Serve };