effect-actors 0.0.1

package/dist/actor/definition.js

@@ -0,0 +1,110 @@
+import { Result } from "effect";
+import { RegistrationError as InvalidDefinition } from "../errors/index.js";
+import { makeClient } from "./client.js";
+import { assertIdentifier, decodeJson, encodeJson, prepareMigrations, validateTransition, } from "./state/codec.js";
+import { layer } from "./state/layer.js";
+export const make = (name, options) => {
+    assertIdentifier(name);
+    if (!Number.isSafeInteger(options.protocolVersion) ||
+        options.protocolVersion < 1 ||
+        !Number.isSafeInteger(options.state.version) ||
+        options.state.version < 1) {
+        throw new InvalidDefinition({
+            message: "Actor protocol and state versions must be positive safe integers",
+        });
+    }
+    const state = Object.freeze({
+        ...options.state,
+        migrations: Object.freeze([...options.state.migrations]),
+    });
+    const migrations = prepareMigrations(state);
+    const build = (commands, queries, reducers, readers) => {
+        const compiled = {
+            name,
+            protocolVersion: options.protocolVersion,
+            stateVersion: state.version,
+            initial: () => encodeJson(state.schema, state.initial()),
+            migrations,
+            commands,
+            queries,
+            reducers,
+            readers,
+        };
+        const protocol = Object.freeze({
+            kind: "state",
+            actorType: name,
+            version: options.protocolVersion,
+            commands,
+            queries,
+            eventSchema: options.events,
+        });
+        return Object.freeze({
+            name,
+            protocolVersion: options.protocolVersion,
+            protocol,
+            state,
+            eventSchema: options.events,
+            commands,
+            queries,
+            client: makeClient({
+                name,
+                protocolVersion: options.protocolVersion,
+                commands,
+                queries,
+                eventSchema: options.events,
+            }),
+            toLayer: (entityOptions) => layer(compiled, entityOptions),
+            command(operation, procedure) {
+                assertIdentifier(operation);
+                if (Object.hasOwn(commands, operation) || Object.hasOwn(queries, operation))
+                    throw new InvalidDefinition({ message: "Duplicate actor operation" });
+                const metadata = Object.freeze({
+                    payload: procedure.payload,
+                    success: procedure.success,
+                    error: procedure.error,
+                });
+                const nextCommands = Object.freeze({ ...commands, [operation]: metadata });
+                const reduce = (address, commandId, payload, turn, limits) => {
+                    const result = procedure.reduce(decodeJson(state.schema, turn.snapshot.state), decodeJson(procedure.payload, payload), {
+                        address,
+                        commandId,
+                        nowMillis: turn.nowMillis,
+                        revision: turn.snapshot.revision,
+                    });
+                    if (Result.isFailure(result))
+                        return Result.fail(encodeJson(procedure.error, result.failure));
+                    const transition = result.success;
+                    const encoded = {
+                        state: encodeJson(state.schema, transition.state),
+                        value: encodeJson(procedure.success, transition.value),
+                        events: (transition.events ?? []).map((event) => encodeJson(options.events, event)),
+                        timers: transition.timers ?? [],
+                        outbox: transition.outbox ?? [],
+                    };
+                    validateTransition(address, encoded, limits);
+                    return Result.succeed(encoded);
+                };
+                return build(nextCommands, queries, { ...reducers, [operation]: reduce }, readers);
+            },
+            query(operation, procedure) {
+                assertIdentifier(operation);
+                if (Object.hasOwn(commands, operation) || Object.hasOwn(queries, operation))
+                    throw new InvalidDefinition({ message: "Duplicate actor operation" });
+                const metadata = Object.freeze({
+                    payload: procedure.payload,
+                    success: procedure.success,
+                    error: procedure.error,
+                });
+                const nextQueries = Object.freeze({ ...queries, [operation]: metadata });
+                const read = (snapshot, payload) => {
+                    const result = procedure.read(decodeJson(state.schema, snapshot), decodeJson(procedure.payload, payload));
+                    return Result.isFailure(result)
+                        ? { _tag: "Failure", error: encodeJson(procedure.error, result.failure) }
+                        : { _tag: "Success", value: encodeJson(procedure.success, result.success) };
+                };
+                return build(commands, nextQueries, reducers, { ...readers, [operation]: read });
+            },
+        });
+    };
+    return build(Object.freeze({}), Object.freeze({}), {}, {});
+};

package/dist/actor/state/codec.d.ts

@@ -0,0 +1,10 @@
+import type { Address, Json, JsonSchema } from "../../protocol/index.js";
+import type { Migration, StateDefinition } from "../definition.js";
+import type { Configuration } from "../../runtime/service.js";
+import type { EncodedTransition } from "../../store/service.js";
+export declare const encodeJson: <S extends JsonSchema>(schema: S, value: S["Type"]) => Json;
+export declare const decodeJson: <S extends JsonSchema>(schema: S, value: Json) => S["Type"];
+export declare const assertIdentifier: (name: string) => void;
+export declare const prepareMigrations: <S extends JsonSchema>(state: StateDefinition<S>) => ReadonlyArray<Migration>;
+export declare const byteLength: (value: Json) => number;
+export declare const validateTransition: (address: Address, transition: EncodedTransition, limits: Configuration) => void;

package/dist/actor/state/codec.js

@@ -0,0 +1,117 @@
+import { Result, Schema } from "effect";
+import { InvalidInput, MigrationRejected, RegistrationError } from "../../errors/index.js";
+import { addressId, canonicalJson, validateId } from "../../protocol/encoding.js";
+export const encodeJson = (schema, value) => {
+    const result = Schema.encodeResult(schema)(value);
+    if (Result.isFailure(result))
+        throw new InvalidInput({ message: "Actor output does not match its schema" });
+    canonicalJson(result.success);
+    return result.success;
+};
+export const decodeJson = (schema, value) => {
+    const result = Schema.decodeUnknownResult(schema)(value, { onExcessProperty: "error" });
+    if (Result.isFailure(result))
+        throw new InvalidInput({ message: "Actor value does not match its schema" });
+    return result.success;
+};
+export const assertIdentifier = (name) => {
+    if (typeof name !== "string" ||
+        name.trim() !== name ||
+        !/^[A-Za-z][A-Za-z0-9_.-]{0,127}$/.test(name) ||
+        ["constructor", "prototype", "__proto__"].includes(name)) {
+        throw new RegistrationError({
+            message: "Actor and operation names must be safe nonempty identifiers",
+        });
+    }
+};
+export const prepareMigrations = (state) => {
+    const sources = new Set();
+    return state.migrations.map((migration) => {
+        if (!Number.isSafeInteger(migration.fromVersion) ||
+            !Number.isSafeInteger(migration.toVersion) ||
+            migration.fromVersion < 1 ||
+            migration.toVersion <= migration.fromVersion ||
+            migration.toVersion > state.version ||
+            sources.has(migration.fromVersion)) {
+            throw new RegistrationError({
+                message: "State migration chain contains an invalid or ambiguous step",
+            });
+        }
+        sources.add(migration.fromVersion);
+        return {
+            fromVersion: migration.fromVersion,
+            toVersion: migration.toVersion,
+            migrate: (input) => {
+                try {
+                    const result = migration.migrate(input);
+                    if (Result.isFailure(result))
+                        return result;
+                    canonicalJson(result.success);
+                    if (migration.toVersion === state.version)
+                        decodeJson(state.schema, result.success);
+                    return result;
+                }
+                catch {
+                    return Result.fail(new MigrationRejected({
+                        fromVersion: migration.fromVersion,
+                        toVersion: migration.toVersion,
+                        message: "State migration failed validation",
+                    }));
+                }
+            },
+        };
+    });
+};
+export const byteLength = (value) => new TextEncoder().encode(canonicalJson(value)).byteLength;
+export const validateTransition = (address, transition, limits) => {
+    if (byteLength(transition.state) > limits.maxStateBytes ||
+        byteLength(transition.value) > limits.maxStateBytes) {
+        throw new InvalidInput({ message: "Actor state or result exceeds the configured byte limit" });
+    }
+    if (transition.events.length > limits.maxEventsPerTurn ||
+        transition.outbox.length > limits.maxOutboxCallsPerTurn ||
+        transition.timers.length > limits.maxTimerChangesPerTurn) {
+        throw new InvalidInput({ message: "Actor turn exceeds its side-effect count limit" });
+    }
+    for (const event of transition.events) {
+        if (byteLength(event) > limits.maxEventBytes)
+            throw new InvalidInput({ message: "Actor event exceeds the configured byte limit" });
+    }
+    for (const timer of transition.timers) {
+        if (!timer ||
+            typeof timer.timerId !== "string" ||
+            timer.timerId.length === 0 ||
+            timer.timerId.length > 256) {
+            throw new InvalidInput({ message: "Invalid timer identity" });
+        }
+        validateId(timer.timerId);
+        if (timer._tag === "Cancel")
+            continue;
+        if (timer._tag !== "Set" || !Number.isSafeInteger(timer.dueAtMillis) || timer.dueAtMillis < 0) {
+            throw new InvalidInput({ message: "Invalid timer schedule" });
+        }
+        if (byteLength(timer.payload) > limits.maxCommandBytes)
+            throw new InvalidInput({ message: "Timer payload is too large" });
+    }
+    for (const call of transition.outbox) {
+        validateId(call.commandId);
+        addressId(call.target);
+        if (call.target.namespace !== address.namespace || call.target.tenant !== address.tenant) {
+            throw new InvalidInput({
+                message: "Outgoing calls must stay within the source namespace and tenant",
+            });
+        }
+        if (!["command", "hosted"].includes(call.kind) ||
+            typeof call.operation !== "string" ||
+            call.operation.length === 0 ||
+            typeof call.commandId !== "string" ||
+            call.commandId.length === 0 ||
+            call.commandId.length > 256 ||
+            !Number.isSafeInteger(call.protocolVersion) ||
+            call.protocolVersion < 1) {
+            throw new InvalidInput({ message: "Invalid outgoing call" });
+        }
+        if (byteLength(call.payload) > limits.maxCommandBytes)
+            throw new InvalidInput({ message: "Outgoing payload is too large" });
+    }
+};

package/dist/actor/state/compiled.d.ts

@@ -0,0 +1,17 @@
+import type { Result } from "effect";
+import type { Json, Outcome, Procedures } from "../../protocol/index.js";
+import type { EncodedTransition, Turn } from "../../store/service.js";
+import type { Address } from "../../protocol/index.js";
+import type { Migration } from "../definition.js";
+import type { Configuration } from "../../runtime/service.js";
+export interface CompiledActor {
+    readonly name: string;
+    readonly protocolVersion: number;
+    readonly stateVersion: number;
+    readonly initial: () => Json;
+    readonly migrations: ReadonlyArray<Migration>;
+    readonly commands: Procedures;
+    readonly queries: Procedures;
+    readonly reducers: Readonly<Record<string, (address: Address, commandId: string, payload: Json, turn: Turn, limits: Configuration) => Result.Result<EncodedTransition, Json>>>;
+    readonly readers: Readonly<Record<string, (state: Json, payload: Json) => Outcome>>;
+}

package/dist/actor/state/compiled.js

@@ -0,0 +1 @@
+export {};

package/dist/actor/state/layer.d.ts

@@ -0,0 +1,7 @@
+import { Layer } from "effect";
+import { RegistrationError } from "../../errors/index.js";
+import { Runtime } from "../../runtime/service.js";
+import { Store } from "../../store/service.js";
+import type { EntityOptions } from "../definition.js";
+import type { CompiledActor } from "./compiled.js";
+export declare const layer: (actor: CompiledActor, options?: EntityOptions) => Layer.Layer<never, RegistrationError, Runtime | Store>;

package/dist/actor/state/layer.js

@@ -0,0 +1,167 @@
+import { Duration, Effect, Layer, Option, Result } from "effect";
+import { Entity } from "effect/unstable/cluster";
+import { HostUnavailable, InvalidInput, MigrationRejected, RegistrationError, UnsupportedVersion, } from "../../errors/index.js";
+import { boundary } from "../../protocol/encoding.js";
+import { Runtime } from "../../runtime/service.js";
+import { decodeAddress } from "../../runtime/cluster/address.js";
+import { validateInvocation } from "../../runtime/cluster/client.js";
+import { makeEntity } from "../../runtime/cluster/protocol.js";
+import { Store } from "../../store/service.js";
+import { byteLength, decodeJson } from "./codec.js";
+const retryInfrastructure = (effect) => effect.pipe(Effect.catchIf((error) => typeof error === "object" &&
+    error !== null &&
+    "_tag" in error &&
+    (error._tag === "effect-actors/OwnershipLost" ||
+        (error._tag === "effect-actors/StorageUnavailable" &&
+            "retryable" in error &&
+            error.retryable === true)), () => Effect.die("Actor storage ownership is temporarily unavailable")));
+export const layer = (actor, options = {}) => Layer.effectDiscard(Effect.gen(function* () {
+    yield* Effect.try({
+        try: () => {
+            if (options.mailboxCapacity !== undefined &&
+                (!Number.isSafeInteger(options.mailboxCapacity) || options.mailboxCapacity < 1))
+                throw new Error();
+            if (options.maxIdleTime !== undefined && !(Duration.toMillis(options.maxIdleTime) > 0))
+                throw new Error();
+        },
+        catch: () => new RegistrationError({ message: "Invalid actor mailbox capacity or idle duration" }),
+    });
+    const runtime = yield* Runtime;
+    const store = yield* Store;
+    const configuration = runtime.configuration;
+    const maximumTurnMillis = Duration.toMillis(configuration.maxTurnDuration);
+    const migrations = actor.migrations.map((migration) => ({
+        ...migration,
+        migrate: (value) => {
+            const result = migration.migrate(value);
+            if (Result.isSuccess(result) &&
+                byteLength(result.success) > configuration.maxStateBytes) {
+                return Result.fail(new MigrationRejected({
+                    fromVersion: migration.fromVersion,
+                    toVersion: migration.toVersion,
+                    message: "Migrated state exceeds the configured byte limit",
+                }));
+            }
+            return result;
+        },
+    }));
+    const entity = makeEntity(configuration.namespace, actor.name);
+    const build = Effect.gen(function* () {
+        const current = yield* Entity.CurrentAddress;
+        const address = yield* Effect.orDie(boundary(() => decodeAddress(configuration.namespace, actor.name, current.entityId)));
+        const ready = yield* Effect.result(Effect.gen(function* () {
+            const owner = yield* store.acquire(address, {
+                leaseDuration: configuration.actorLeaseDuration,
+                renewEvery: configuration.actorLeaseRenewEvery,
+            });
+            const initial = yield* boundary(actor.initial);
+            yield* boundary(() => {
+                if (byteLength(initial) > configuration.maxStateBytes)
+                    throw new InvalidInput({
+                        message: "Initial state exceeds the configured byte limit",
+                    });
+            });
+            const snapshot = yield* store.initialize(owner, {
+                currentVersion: actor.stateVersion,
+                initial,
+                migrations,
+            });
+            yield* boundary(() => {
+                if (byteLength(snapshot.state) > configuration.maxStateBytes)
+                    throw new InvalidInput({
+                        message: "Stored state exceeds the configured byte limit",
+                    });
+            });
+            return owner;
+        }));
+        const withOwner = (run) => retryInfrastructure(Result.isFailure(ready)
+            ? Effect.fail(ready.failure)
+            : Effect.raceFirst(run(ready.success), ready.success.lost));
+        const evaluate = (command, commandId, payload, turn) => {
+            const reduce = Object.hasOwn(actor.reducers, command)
+                ? actor.reducers[command]
+                : undefined;
+            if (!reduce)
+                throw new InvalidInput({ message: "Unknown actor command" });
+            const start = performance.now();
+            const result = reduce(address, commandId, payload, turn, configuration);
+            if (performance.now() - start > maximumTurnMillis)
+                throw new InvalidInput({ message: "Actor reducer exceeded its turn budget" });
+            if (Result.isFailure(result) && byteLength(result.failure) > configuration.maxStateBytes)
+                throw new InvalidInput({ message: "Actor error exceeds the configured byte limit" });
+            if (Result.isFailure(result))
+                return result;
+            for (const timer of result.success.timers) {
+                if (timer._tag !== "Set")
+                    continue;
+                const target = Object.hasOwn(actor.commands, timer.command)
+                    ? actor.commands[timer.command]
+                    : undefined;
+                if (!target)
+                    throw new InvalidInput({ message: "Timer targets an unknown command" });
+                decodeJson(target.payload, timer.payload);
+            }
+            return result;
+        };
+        return entity.of({
+            Command: ({ payload }) => withOwner((owner) => Effect.gen(function* () {
+                const input = { ...payload, address };
+                yield* boundary(() => validateInvocation(input, configuration));
+                if (payload.protocolVersion !== actor.protocolVersion)
+                    return yield* new UnsupportedVersion({
+                        actorType: actor.name,
+                        version: payload.protocolVersion,
+                    });
+                const reduce = Object.hasOwn(actor.reducers, payload.command)
+                    ? actor.reducers[payload.command]
+                    : undefined;
+                if (!reduce)
+                    return yield* new InvalidInput({ message: "Unknown actor command" });
+                return yield* store.transact(owner, input, (turn) => evaluate(payload.command, payload.commandId, payload.payload, turn));
+            })),
+            Query: ({ payload }) => withOwner((owner) => Effect.gen(function* () {
+                if (payload.protocolVersion !== actor.protocolVersion)
+                    return yield* new UnsupportedVersion({
+                        actorType: actor.name,
+                        version: payload.protocolVersion,
+                    });
+                const read = Object.hasOwn(actor.readers, payload.query)
+                    ? actor.readers[payload.query]
+                    : undefined;
+                if (!read)
+                    return yield* new InvalidInput({ message: "Unknown actor query" });
+                yield* boundary(() => {
+                    if (byteLength(payload.payload) > configuration.maxCommandBytes)
+                        throw new InvalidInput({
+                            message: "Query payload exceeds the configured byte limit",
+                        });
+                });
+                return yield* store.query(owner, (snapshot) => {
+                    const start = performance.now();
+                    const value = read(snapshot.state, payload.payload);
+                    if (performance.now() - start > maximumTurnMillis)
+                        throw new InvalidInput({ message: "Actor query exceeded its turn budget" });
+                    if (byteLength(value._tag === "Success" ? value.value : value.error) >
+                        configuration.maxStateBytes)
+                        throw new InvalidInput({
+                            message: "Query output exceeds the configured byte limit",
+                        });
+                    return { revision: snapshot.revision, cursor: snapshot.cursor, value };
+                });
+            })),
+            Receipt: ({ payload }) => retryInfrastructure(store.receipt(address, payload.commandId)).pipe(Effect.map(Option.getOrNull)),
+            Events: ({ payload }) => retryInfrastructure(store.events(address, payload)),
+            Wake: ({ payload }) => withOwner((owner) => store.fireTimer(owner, { address, ...payload }, (command, value, turn) => {
+                return evaluate(command, `~effect-actors/timer/${JSON.stringify([payload.timerId, payload.generation])}`, value, turn);
+            })).pipe(Effect.map(Option.getOrNull)),
+            Action: () => Effect.fail(new HostUnavailable({ retryable: false })),
+            DurableAction: () => Effect.fail(new HostUnavailable({ retryable: false })),
+        });
+    });
+    yield* runtime.register({
+        actorType: actor.name,
+        protocolVersion: actor.protocolVersion,
+        kind: "state",
+        entity: entity.toLayer(build, { ...options, concurrency: 1 }),
+    });
+}));

package/dist/client/http/errors.d.ts

@@ -0,0 +1,30 @@
+import { Effect, Schema } from "effect";
+import { CursorExpired, HostUnavailable, InvalidInput, StorageUnavailable } from "../../errors/index.js";
+import type { CommandError, ReadError } from "../../errors/index.js";
+import type { Json } from "../../protocol/index.js";
+import type { GatewayError as RemoteError } from "../../gateway/wire.js";
+export interface ErrorContext {
+    readonly commandId?: string;
+    readonly actorType: string;
+    readonly protocolVersion?: number;
+}
+export declare const isSuccess: (status: number) => boolean;
+export declare const invalid: () => InvalidInput;
+export declare const unavailable: () => StorageUnavailable;
+export declare const remoteCommandError: (error: RemoteError, context: ErrorContext) => CommandError;
+export declare const remoteReadError: (error: RemoteError, context: ErrorContext) => ReadError | CursorExpired;
+export declare const parseCommandError: (response: {
+    readonly json: Effect.Effect<Json, unknown>;
+}, context: ErrorContext, fallback: CommandError) => Effect.Effect<never, CommandError>;
+export declare const parseReadError: (response: {
+    readonly json: Effect.Effect<Json, unknown>;
+}, context: ErrorContext) => Effect.Effect<never, ReadError | CursorExpired>;
+export declare const parseReadOnlyError: (response: {
+    readonly json: Effect.Effect<Json, unknown>;
+}, context: ErrorContext) => Effect.Effect<never, ReadError>;
+export declare const parseHostedError: (response: {
+    readonly json: Effect.Effect<Json, unknown>;
+}, context: ErrorContext) => Effect.Effect<never, CommandError | HostUnavailable>;
+export declare const responseJson: <S extends Schema.ConstraintDecoder<unknown>, E>(response: {
+    readonly json: Effect.Effect<Json, unknown>;
+}, schema: S, fallback: E) => Effect.Effect<S["Type"], E>;

package/dist/client/http/errors.js

@@ -0,0 +1,72 @@
+import { Effect, Schema } from "effect";
+import { CommandConflict, CursorExpired, HostUnavailable, InvalidInput, OutcomeUnknown, Overloaded, RevisionConflict, StorageUnavailable, Unauthorized, UnsupportedVersion, } from "../../errors/index.js";
+import { decode } from "../../protocol/index.js";
+import { GatewayErrorResponse } from "../../gateway/wire.js";
+export const isSuccess = (status) => status >= 200 && status < 300;
+export const invalid = () => new InvalidInput({ message: "Invalid HTTP actor request" });
+export const unavailable = () => new StorageUnavailable({ retryable: true });
+export const remoteCommandError = (error, context) => {
+    switch (error.code) {
+        case "InvalidInput":
+        case "NotFound":
+            return invalid();
+        case "Unauthorized":
+        case "Unauthenticated":
+            return new Unauthorized({ message: "Gateway rejected access" });
+        case "Overloaded":
+            return new Overloaded({ retryAfterMillis: error.retryAfterMillis ?? 1_000 });
+        case "UnsupportedVersion":
+            return new UnsupportedVersion({
+                actorType: context.actorType,
+                version: context.protocolVersion ?? 0,
+            });
+        case "CommandConflict":
+            return new CommandConflict({ commandId: error.commandId ?? context.commandId ?? "" });
+        case "RevisionConflict":
+            return new RevisionConflict({ expected: error.expected ?? "", actual: error.actual ?? "" });
+        case "OutcomeUnknown":
+            return new OutcomeUnknown({ commandId: error.commandId ?? context.commandId ?? "" });
+        case "HostUnavailable":
+        case "Unavailable":
+        case "SlowConsumer":
+        case "CursorExpired":
+            return context.commandId === undefined
+                ? unavailable()
+                : new OutcomeUnknown({ commandId: context.commandId });
+        default:
+            return context.commandId === undefined
+                ? unavailable()
+                : new OutcomeUnknown({ commandId: context.commandId });
+    }
+};
+export const remoteReadError = (error, context) => {
+    if (error.code === "CursorExpired")
+        return new CursorExpired({ message: "Event cursor has expired" });
+    const commandError = remoteCommandError(error, context);
+    switch (commandError._tag) {
+        case "effect-actors/InvalidInput":
+        case "effect-actors/Unauthorized":
+        case "effect-actors/Overloaded":
+        case "effect-actors/UnsupportedVersion":
+            return commandError;
+        default:
+            return unavailable();
+    }
+};
+export const parseCommandError = (response, context, fallback) => response.json.pipe(Effect.flatMap((body) => decode(GatewayErrorResponse, body)), Effect.matchEffect({
+    onFailure: () => Effect.fail(fallback),
+    onSuccess: ({ error }) => Effect.fail(remoteCommandError(error, context)),
+}));
+export const parseReadError = (response, context) => response.json.pipe(Effect.flatMap((body) => decode(GatewayErrorResponse, body)), Effect.matchEffect({
+    onFailure: () => Effect.fail(unavailable()),
+    onSuccess: ({ error }) => Effect.fail(remoteReadError(error, context)),
+}));
+export const parseReadOnlyError = (response, context) => parseReadError(response, context).pipe(Effect.catchIf((error) => error instanceof CursorExpired, () => Effect.fail(unavailable())));
+const remoteHostedError = (error, context) => error.code === "HostUnavailable"
+    ? new HostUnavailable({ retryable: true })
+    : remoteCommandError(error, context);
+export const parseHostedError = (response, context) => response.json.pipe(Effect.flatMap((body) => decode(GatewayErrorResponse, body)), Effect.matchEffect({
+    onFailure: () => Effect.fail(new HostUnavailable({ retryable: true })),
+    onSuccess: ({ error }) => Effect.fail(remoteHostedError(error, context)),
+}));
+export const responseJson = (response, schema, fallback) => response.json.pipe(Effect.flatMap((body) => decode(schema, body)), Effect.mapError(() => fallback));

package/dist/client/http/events.d.ts

@@ -0,0 +1,10 @@
+import { Effect, Stream } from "effect";
+import { CursorExpired, InvalidInput } from "../../errors/index.js";
+import type { ReadError } from "../../errors/index.js";
+import type { Address, Event, Json } from "../../protocol/index.js";
+import type { ErrorContext } from "./errors.js";
+export declare const eventsUrl: (baseUrl: string, address: Address, after: string) => string;
+export declare const validateCursor: (address: Address, cursor: string) => Effect.Effect<string, InvalidInput>;
+export declare const decodeEventStream: (stream: Stream.Stream<Uint8Array, unknown>, context: ErrorContext & {
+    readonly address: Address;
+}) => Stream.Stream<Event<Json>, ReadError | CursorExpired>;

package/dist/client/http/events.js

@@ -0,0 +1,30 @@
+import { Effect, Encoding, Stream } from "effect";
+import { Sse } from "effect/unstable/encoding";
+import { CursorExpired, InvalidInput } from "../../errors/index.js";
+import { boundary, canonicalJson, decode, readCursor } from "../../protocol/index.js";
+import { Event as EventSchema } from "../../protocol/schemas.js";
+import { GatewayError } from "../../gateway/wire.js";
+import { invalid, remoteReadError, unavailable } from "./errors.js";
+const segment = (value) => encodeURIComponent(value);
+export const eventsUrl = (baseUrl, address, after) => {
+    const key = Encoding.encodeBase64Url(canonicalJson(address.key));
+    return `${baseUrl}/${segment(address.tenant)}/${segment(address.actorType)}/events?key=${key}&after=${segment(after)}`;
+};
+export const validateCursor = (address, cursor) => boundary(() => readCursor(address, cursor));
+const decodeSse = (event, context) => {
+    if (event.event === "actor-error") {
+        return boundary(() => JSON.parse(event.data)).pipe(Effect.flatMap((body) => decode(GatewayError, body)), Effect.mapError(() => unavailable()), Effect.flatMap((error) => Effect.fail(remoteReadError(error, context))));
+    }
+    if (event.event !== "actor-event" || event.id === undefined)
+        return Effect.fail(invalid());
+    return boundary(() => JSON.parse(event.data)).pipe(Effect.flatMap((body) => decode(EventSchema, body)), Effect.flatMap((decoded) => decoded.cursor === event.id
+        ? validateCursor(context.address, decoded.cursor).pipe(Effect.as(decoded))
+        : Effect.fail(invalid())), Effect.mapError(() => invalid()));
+};
+export const decodeEventStream = (stream, context) => stream.pipe(Stream.decodeText, Stream.pipeThroughChannel(Sse.decode()), Stream.mapEffect((event) => decodeSse(event, context)), Stream.mapError((error) => {
+    if (error instanceof InvalidInput || error instanceof CursorExpired)
+        return error;
+    if (typeof error === "object" && error !== null && error._tag)
+        return error;
+    return unavailable();
+}));

package/dist/client/http/layer.d.ts

@@ -0,0 +1,5 @@
+import { Layer } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { Client } from "../service.js";
+import type { HttpOptions } from "../service.js";
+export declare const layerHttp: (options: HttpOptions) => Layer.Layer<Client, never, HttpClient.HttpClient>;