liminal 0.17.14 → 0.17.16

package/ActorRuntime.ts

@@ -0,0 +1,449 @@
+import { DurableObject } from "cloudflare:workers"
+import {
+  Layer,
+  Effect,
+  Scope,
+  Schema as S,
+  Context,
+  ManagedRuntime,
+  ConfigProvider,
+  Duration,
+  flow,
+  Option,
+  Tracer,
+  pipe,
+  Exit,
+} from "effect"
+import { DoState } from "effect-workerd"
+import { Env } from "effect-workerd"
+import { Clock } from "effect-workerd/platform"
+import { SecWebSocketProtocol } from "effect-workerd/socket_util"
+import { Headers, FetchHttpClient, HttpClient, HttpTraceContext } from "effect/unstable/http"
+import * as Boundary from "liminal-util/Boundary"
+import { type TopFromString, encodeJsonString, decodeJsonString } from "liminal-util/schema"
+
+import type { ActorNamespace } from "./ActorNamespace.ts"
+import type { ActorTransport } from "./ActorTransport.ts"
+import * as ClientDirectory from "./ClientDirectory.ts"
+import type { ClientHandle } from "./ClientHandle.ts"
+import type { Handlers, Methods } from "./Method.ts"
+import type { ProtocolDefinition } from "./Protocol.ts"
+import * as Tracing from "./Tracing.ts"
+import { sessionAttributes, SessionId, sessionLink } from "./Tracing.ts"
+
+export interface ActorRuntimeDefinition<
+  NamespaceSelf,
+  NamespaceId extends string,
+  Internal extends Methods,
+  ActorSelf,
+  ActorId extends string,
+  Name extends TopFromString,
+  AttachmentFields extends S.Struct.Fields,
+  ClientSelf,
+  ClientId extends string,
+  D extends ProtocolDefinition,
+  PreludeROut,
+  PreludeE,
+  RunROut,
+  RunE,
+> {
+  readonly ""?: this["namespace"]["definition"]["actor"]["definition"]["client"]["protocol"]
+
+  readonly namespace: ActorNamespace<
+    NamespaceSelf,
+    NamespaceId,
+    Internal,
+    ActorSelf,
+    ActorId,
+    Name,
+    AttachmentFields,
+    ClientSelf,
+    ClientId,
+    D
+  >
+
+  readonly prelude: Layer.Layer<
+    | PreludeROut
+    | NonNullable<this[""]>["F"]["Payload"]["DecodingServices"]
+    | NonNullable<this[""]>["F"]["Success"]["EncodingServices"]
+    | NonNullable<this[""]>["F"]["Failure"]["EncodingServices"]
+    | NonNullable<this[""]>["Event"]["EncodingServices"]
+    | S.Struct<AttachmentFields>["DecodingServices"]
+    | S.Struct<AttachmentFields>["EncodingServices"]
+    | Name["EncodingServices"]
+    | Name["DecodingServices"],
+    PreludeE,
+    HttpClient.HttpClient | Env
+  >
+
+  readonly layer: Layer.Layer<RunROut, RunE, ActorSelf | HttpClient.HttpClient | Env | PreludeROut>
+
+  readonly external: Handlers<
+    D["external"],
+    ActorSelf | HttpClient.HttpClient | Env | PreludeROut | RunROut | Scope.Scope
+  >
+
+  readonly internal: Handlers<Internal, ActorSelf | HttpClient.HttpClient | PreludeROut | RunROut | Scope.Scope>
+
+  readonly hydrate: Effect.Effect<
+    S.Struct<D["state"]>["Type"],
+    never,
+    ActorSelf | HttpClient.HttpClient | Env | PreludeROut | RunROut | Scope.Scope
+  >
+
+  readonly onDisconnect: Effect.Effect<
+    void,
+    never,
+    ActorSelf | HttpClient.HttpClient | Env | PreludeROut | RunROut | Scope.Scope
+  >
+
+  readonly hibernation?: Duration.Input | undefined
+}
+
+export const make = <
+  NamespaceSelf,
+  NamespaceId extends string,
+  Internal extends Methods,
+  ActorSelf,
+  ActorId extends string,
+  Name extends TopFromString,
+  AttachmentFields extends S.Struct.Fields,
+  ClientSelf,
+  ClientId extends string,
+  D extends ProtocolDefinition,
+  PreludeROut,
+  PreludeE,
+  RunROut,
+  RunE,
+>(
+  definition: ActorRuntimeDefinition<
+    NamespaceSelf,
+    NamespaceId,
+    Internal,
+    ActorSelf,
+    ActorId,
+    Name,
+    AttachmentFields,
+    ClientSelf,
+    ClientId,
+    D,
+    PreludeROut,
+    PreludeE,
+    RunROut,
+    RunE
+  >,
+): new (state: DurableObjectState<{}>, env: Cloudflare.Env) => DurableObject => {
+  const {
+    hibernation,
+    prelude,
+    external,
+    layer,
+    hydrate,
+    onDisconnect,
+    internal,
+    namespace: {
+      definition: { actor },
+    },
+  } = definition
+  const {
+    definition: {
+      name: Name,
+      client: { protocol: P },
+      attachments: AttachmentFields,
+    },
+  } = actor
+
+  const Attachments = S.Struct(AttachmentFields)
+  const SocketAttachment = S.Struct({
+    attachments: S.toCodecJson(Attachments),
+    session: Tracing.Session,
+  })
+  const encodeSocketAttachment = S.encodeEffect(SocketAttachment)
+  const decodeSocketAttachment = S.decodeUnknownEffect(SocketAttachment)
+  const decodeAttachmentsString = decodeJsonString(Attachments)
+  const encodeAuditionSuccess = encodeJsonString(P.Audition.Success)
+  const decodeClient = decodeJsonString(P.Client)
+  const encodeFSuccess = encodeJsonString(P.F.Success)
+  const encodeFFailure = encodeJsonString(P.F.Failure)
+  const encodeEvent = encodeJsonString(P.Event)
+
+  const transport: ActorTransport<
+    WebSocket,
+    {
+      readonly socket: WebSocket
+      readonly session: typeof Tracing.Session.Type
+    },
+    AttachmentFields,
+    D
+  > = {
+    key: ({ socket }) => socket,
+    send: ({ socket, session }, event) => {
+      const { _tag } = event.event as never
+      return Effect.gen(function* () {
+        const trace = yield* Tracing.currentTrace
+        const encoded = yield* encodeEvent({ ...event, ...(trace && { trace }) }).pipe(
+          Effect.catchTags({
+            SchemaError: Effect.die,
+          }),
+        )
+        // @effect-diagnostics-next-line tryCatchInEffectGen:off
+        try {
+          socket.send(encoded)
+          // oxlint-disable-next-line no-unused-vars
+        } catch (_e) {}
+      }).pipe(
+        Boundary.span("send", import.meta.url, {
+          attributes: { _tag, ...sessionAttributes(session) },
+          kind: "producer",
+          links: [sessionLink(session)],
+        }),
+      )
+    },
+    close: ({ socket }) => Effect.sync(() => socket.close(1000)),
+    snapshot: ({ socket, session }, attachments) =>
+      encodeSocketAttachment({ attachments, session }).pipe(
+        Effect.catchTags({
+          SchemaError: Effect.die,
+        }),
+        Effect.andThen((v) => Effect.sync(() => socket.serializeAttachment(v))),
+      ),
+  }
+
+  class NameDecoded extends Context.Service<NameDecoded, Name["Type"]>()("liminal/ActorNamespace/NameDecoded") {}
+
+  return class extends DurableObject {
+    readonly run
+    readonly directory = ClientDirectory.make(actor, { transport })
+    readonly provideActor = (currentClient: ClientHandle<ActorSelf, AttachmentFields, D>) =>
+      flow(
+        Effect.provide(
+          Layer.provideMerge(
+            layer,
+            Effect.gen({ self: this }, function* () {
+              const name = yield* NameDecoded
+              return Layer.succeed(actor, {
+                name,
+                clients: this.directory.handles,
+                currentClient,
+              })
+            }).pipe(Layer.unwrap),
+          ),
+        ),
+        Effect.scoped,
+      )
+    constructor(state: DurableObjectState<{}>, env: Cloudflare.Env) {
+      super(state, env)
+      if (hibernation) {
+        Option.andThen(
+          Duration.fromInput(hibernation),
+          flow(Duration.toMillis, (timeout) => state.setHibernatableWebSocketEventTimeout(timeout)),
+        )
+      }
+
+      const Live = Layer.mergeAll(
+        FetchHttpClient.layer,
+        Layer.succeed(DoState.DoState, state),
+        Layer.succeed(Env, env as never),
+        Layer.effect(NameDecoded, S.decodeUnknownEffect(Name)(state.id.name)),
+      ).pipe(
+        Layer.provideMerge(
+          prelude.pipe(
+            Layer.provideMerge(
+              Layer.mergeAll(
+                FetchHttpClient.layer,
+                ConfigProvider.layer(ConfigProvider.fromUnknown(env)),
+                Layer.succeed(Env, env as never),
+              ),
+            ),
+          ),
+        ),
+        Layer.provideMerge(Clock.layer),
+      )
+
+      const HydrateClientsLive = Effect.gen({ self: this }, function* () {
+        for (const socket of state.getWebSockets()) {
+          const { attachments, session } = yield* decodeSocketAttachment(socket.deserializeAttachment())
+          yield* this.directory
+            .register({ socket, session }, attachments)
+            .pipe(Effect.linkSpans(Tracer.externalSpan(session.trace), sessionLink(session).attributes))
+        }
+      }).pipe(Boundary.span("hydrate", import.meta.url), Layer.effectDiscard)
+
+      const runtime = ManagedRuntime.make(
+        HydrateClientsLive.pipe(Layer.provideMerge(Live), Boundary.layer("actor", import.meta.url)),
+      )
+      this.run = <A, E, R extends ManagedRuntime.ManagedRuntime.Services<typeof runtime>>(
+        effect: Effect.Effect<A, E, R>,
+      ) => Effect.onError(effect, Effect.logError).pipe(runtime.runPromise)
+    }
+
+    override fetch(request: Request): Promise<Response> {
+      return Effect.gen({ self: this }, function* () {
+        const url = new URL(request.url)
+        const attachments = yield* decodeAttachmentsString(url.searchParams.get("__liminal_attachments"))
+        const clientId = yield* Effect.fromNullishOr(url.searchParams.get("__liminal_client_id"))
+        const { 0: webSocket, 1: server } = new WebSocketPair()
+        const state = yield* DoState.DoState
+        const session = {
+          id: SessionId.make(clientId),
+          trace: yield* Effect.currentSpan.pipe(Effect.map(Tracing.toTraceEnvelope)),
+        }
+        const currentClient = yield* this.directory.register({ socket: server, session }, attachments)
+        state.acceptWebSocket(server)
+        const initial = yield* hydrate.pipe(
+          this.provideActor(currentClient),
+          Boundary.span("hydrate", import.meta.url, {
+            attributes: sessionAttributes(session),
+            links: [sessionLink(session)],
+          }),
+        )
+        server.send(yield* encodeAuditionSuccess({ _tag: "Audition.Success", initial }))
+        return new Response(null, {
+          status: 101,
+          webSocket,
+          headers: { [SecWebSocketProtocol]: "liminal" },
+        })
+      }).pipe(
+        Boundary.span("fetch", import.meta.url, {
+          kind: "server",
+          parent: pipe(request.headers, Headers.fromInput, HttpTraceContext.fromHeaders, Option.getOrUndefined),
+        }),
+        this.run,
+      )
+    }
+
+    override webSocketMessage(socket: WebSocket, raw: string | ArrayBuffer) {
+      Effect.gen({ self: this }, function* () {
+        const { client, handle: currentClient } = yield* this.directory.entry(socket)
+        const { session } = client
+        yield* Effect.annotateCurrentSpan(sessionAttributes(session))
+        const message = yield* decodeClient(raw instanceof ArrayBuffer ? new TextDecoder().decode(raw) : raw)
+        if (message._tag === "Audition.Payload") {
+          return yield* Effect.die(undefined)
+        }
+        if (message._tag === "Disconnect") {
+          yield* currentClient.disconnect
+          return yield* onDisconnect.pipe(
+            this.provideActor(currentClient),
+            Boundary.span("disconnect", import.meta.url, {
+              attributes: sessionAttributes(session),
+              links: [sessionLink(session)],
+            }),
+          )
+        }
+        const { id, payload } = message
+        const { _tag, value } = payload as never
+        const parent = message.trace ? Tracer.externalSpan(message.trace) : undefined
+        const transportSpan = yield* Tracing.parent
+        const links = [
+          sessionLink(session),
+          ...(parent && transportSpan
+            ? [
+                {
+                  span: transportSpan,
+                  attributes: {
+                    "liminal.link": "transport",
+                    "liminal.transport": "websocket",
+                  },
+                },
+              ]
+            : []),
+        ]
+        yield* external[_tag]!(value).pipe(
+          Effect.matchEffect({
+            onSuccess: (value) =>
+              encodeFSuccess({
+                _tag: "F.Success",
+                id,
+                success: { _tag, value } as never,
+              }),
+            onFailure: (value) =>
+              encodeFFailure({
+                _tag: "F.Failure",
+                id,
+                failure: { _tag, value } as never,
+              }),
+          }),
+          Effect.andThen((v) =>
+            Effect.try({
+              try: () => socket.send(v),
+              catch: () => {},
+            }),
+          ),
+          this.provideActor(currentClient),
+          Boundary.span("handler", import.meta.url, {
+            attributes: { _tag, ...sessionAttributes(session) },
+            kind: "server",
+            parent,
+            links,
+          }),
+        )
+      }).pipe(Boundary.span("socket-message", import.meta.url), this.run)
+    }
+
+    override webSocketClose(socket: WebSocket, _code: number, _reason: string, _wasClean: boolean) {
+      Effect.gen({ self: this }, function* () {
+        const entry = yield* this.directory.entry(socket).pipe(
+          Effect.catchTags({
+            NoSuchElementError: () => Effect.undefined,
+          }),
+        )
+        if (!entry) {
+          return
+        }
+        const {
+          client: { session },
+          handle: currentClient,
+        } = entry
+        yield* Effect.annotateCurrentSpan(sessionAttributes(session))
+        yield* this.directory.unregister(socket)
+        yield* onDisconnect.pipe(
+          this.provideActor(currentClient),
+          Boundary.span("disconnect", import.meta.url, {
+            attributes: sessionAttributes(session),
+            links: [sessionLink(session)],
+          }),
+        )
+      }).pipe(Boundary.span("socket-close", import.meta.url), this.run)
+    }
+
+    override webSocketError(socket: WebSocket, cause: unknown) {
+      Effect.gen({ self: this }, function* () {
+        const {
+          client: { session },
+          handle: currentClient,
+        } = yield* this.directory.entry(socket)
+        yield* Effect.annotateCurrentSpan(sessionAttributes(session))
+        yield* this.directory.unregister(socket)
+        yield* onDisconnect.pipe(
+          this.provideActor(currentClient),
+          Boundary.span("disconnect", import.meta.url, {
+            attributes: sessionAttributes(session),
+            links: [sessionLink(session)],
+          }),
+        )
+        yield* Effect.annotateLogs(Effect.logDebug("SocketErrored"), { cause })
+      }).pipe(Boundary.span("socket-error", import.meta.url), this.run)
+    }
+
+    async rpc<K extends keyof Internal>(
+      method: K,
+      payload: Internal[K]["payload"]["Type"],
+    ): Promise<Exit.Exit<Internal[K]["success"]["Type"], Internal[K]["failure"]["Type"]>> {
+      const handler = internal[method]
+      return await handler(payload).pipe(
+        this.provideActor(null!),
+        Boundary.span("fn-internal", import.meta.url),
+        Effect.exit,
+        this.run,
+      )
+    }
+
+    async proxySendAll<K extends keyof D["events"]>(event: K, payload: S.Struct<D["events"][K]>["Type"]) {
+      await Effect.gen(function* () {
+        const { clients } = yield* actor
+        yield* Effect.forEach(clients, ({ send }) => send(event, payload), { concurrency: "unbounded" })
+      }).pipe(this.provideActor(null!), Boundary.span("fn-internal", import.meta.url), this.run)
+    }
+  }
+}

package/ActorTransport.ts

@@ -2,16 +2,18 @@ import { Effect, Schema as S } from "effect"
 
 import type { Protocol, ProtocolDefinition } from "./Protocol.ts"
 
-export interface ActorTransport<Raw, AttachmentFields extends S.Struct.Fields, D extends ProtocolDefinition> {
+export interface ActorTransport<Key, Client, AttachmentFields extends S.Struct.Fields, D extends ProtocolDefinition> {
+  readonly key: (client: Client) => Key
+
   readonly send: (
-    transport: Raw,
+    client: Client,
     event: Protocol<D>["Event"]["Type"],
-  ) => Effect.Effect<void, S.SchemaError, Protocol<D>["Event"]["EncodingServices"]>
+  ) => Effect.Effect<void, never, Protocol<D>["Event"]["EncodingServices"]>
 
-  readonly close: (transport: Raw) => Effect.Effect<void>
+  readonly close: (client: Client) => Effect.Effect<void>
 
   readonly snapshot: (
-    transport: Raw,
+    client: Client,
     attachments: S.Struct<AttachmentFields>["Type"],
-  ) => Effect.Effect<void, S.SchemaError, S.Struct<AttachmentFields>["EncodingServices"]>
+  ) => Effect.Effect<void, never, S.Struct<AttachmentFields>["EncodingServices"]>
 }

package/Audition.ts

@@ -1,80 +1,126 @@
-import { Schema as S, Pipeable, Stream, Effect, Function } from "effect"
+import { Schema as S, Pipeable, Stream, Effect, Function, Types } from "effect"
 
-import type { F } from "./F.ts"
-import type { ProtocolDefinition } from "./Protocol.ts"
-
-import { diagnostic } from "./_diagnostic.ts"
 import * as Client from "./Client.ts"
 import { type ClientError, AuditionError } from "./errors.ts"
-
-const { debug, span } = diagnostic("Audition")
+import type { Fn } from "./Fn.ts"
+import type { Methods } from "./Method.ts"
+import type { ProtocolDefinition } from "./Protocol.ts"
 
 const TypeId = "~liminal/Audition" as const
 
-export interface Audition<ClientSelf, D extends ProtocolDefinition> extends Pipeable.Pipeable {
+export interface Audition<AuditionSelf, State extends S.Union<ReadonlyArray<S.Top>>, External extends Methods, Event>
+  extends Pipeable.Pipeable {
   readonly [TypeId]: typeof TypeId
 
-  readonly events: Stream.Stream<
-    ReturnType<typeof S.TaggedUnion<D["events"]>>["Type"],
-    ClientError | S.SchemaError,
-    ClientSelf
-  >
+  readonly state: Stream.Stream<State["Type"], ClientError | S.SchemaError, AuditionSelf | State["DecodingServices"]>
+
+  readonly fn: Fn<AuditionSelf, External>
 
-  readonly f: F<ClientSelf, D>
+  readonly events: Stream.Stream<Event, ClientError | S.SchemaError, AuditionSelf>
 }
 
-export const empty: Audition<never, never> = {
+type MergeMethods<T extends Methods, U extends Methods> = [keyof T] extends [never]
+  ? U
+  : { [K in keyof T & keyof U]: Types.Equals<T[K], U[K]> extends true ? T[K] : never }
+
+type MergeState<State, D extends ProtocolDefinition> = [State] extends [never]
+  ? S.Union<[S.Struct<D["state"]>]>
+  : State extends S.Union<ReadonlyArray<S.Top>>
+    ? S.Union<[...State["members"], S.Struct<D["state"]>]>
+    : never
+
+export const empty: Audition<never, never, {}, never> = {
   [TypeId]: TypeId,
   pipe() {
     return Pipeable.pipeArguments(this, arguments)
   },
+  state: Stream.fail(new AuditionError()),
+  fn: () => () => new AuditionError(),
   events: Stream.fail(new AuditionError()),
-  f: () => () => new AuditionError().asEffect(),
 }
 
+export const cycleOn =
+  <Event>(predicate: (event: Event) => boolean) =>
+  <AuditionSelf, State extends S.Union<ReadonlyArray<S.Top>>, External extends Methods>(
+    audition: Audition<AuditionSelf, State, External, Event>,
+  ): Audition<AuditionSelf, State, External, Event> => {
+    const events = audition.events.pipe(Stream.takeUntil(predicate), Stream.forever)
+    const state = audition.state.pipe(Stream.forever)
+
+    return {
+      [TypeId]: TypeId,
+      pipe() {
+        return Pipeable.pipeArguments(this, arguments)
+      },
+      events,
+      fn: audition.fn,
+      state,
+    }
+  }
+
 export const add: {
   <ClientSelf, ClientId extends string, ClientD extends ProtocolDefinition>(
     client: Client.Client<ClientSelf, ClientId, ClientD>,
-  ): <AuditionSelf, AuditionD extends ProtocolDefinition>(
-    audition: Audition<AuditionSelf, AuditionD>,
-  ) => Audition<AuditionSelf | ClientSelf, ProtocolDefinition.Merge<AuditionD, ClientD>>
+  ): <AuditionSelf, State extends S.Union<ReadonlyArray<S.Top>> | never, External extends Methods, Event>(
+    audition: Audition<AuditionSelf, State, External, Event>,
+  ) => Audition<
+    AuditionSelf | ClientSelf,
+    MergeState<State, ClientD>,
+    MergeMethods<External, ClientD["external"]>,
+    Event | ReturnType<typeof S.TaggedUnion<ClientD["events"]>>["Type"]
+  >
   <
-    AuditionClientSelf,
-    AuditionD extends ProtocolDefinition,
+    AuditionSelf,
+    State extends S.Union<ReadonlyArray<S.Top>> | never,
+    External extends Methods,
+    Event,
     ClientSelf,
     ClientId extends string,
     ClientD extends ProtocolDefinition,
   >(
-    audition: Audition<AuditionClientSelf, AuditionD>,
+    audition: Audition<AuditionSelf, State, External, Event>,
     client: Client.Client<ClientSelf, ClientId, ClientD>,
-  ): Audition<AuditionClientSelf | ClientSelf, ProtocolDefinition.Merge<AuditionD, ClientD>>
+  ): Audition<
+    AuditionSelf | ClientSelf,
+    MergeState<State, ClientD>,
+    MergeMethods<External, ClientD["external"]>,
+    Event | ReturnType<typeof S.TaggedUnion<ClientD["events"]>>["Type"]
+  >
 } = Function.dual(
   2,
   <
     AuditionSelf,
-    AuditionD extends ProtocolDefinition,
+    State extends S.Union<ReadonlyArray<S.Top>>,
+    External extends Methods,
+    Event,
     ClientSelf,
     ClientId extends string,
     ClientD extends ProtocolDefinition,
   >(
-    audition: Audition<AuditionSelf, AuditionD>,
+    audition: Audition<AuditionSelf, State, External, Event>,
     client: Client.Client<ClientSelf, ClientId, ClientD>,
-  ): Audition<AuditionSelf | ClientSelf, ProtocolDefinition.Merge<AuditionD, ClientD>> => {
-    const f: F<AuditionSelf | ClientSelf, ProtocolDefinition.Merge<AuditionD, ClientD>> = (method) => (payload) =>
-      audition
-        .f(method)(payload)
-        .pipe(
-          Effect.catchTag("AuditionError", () => client.f(method)(payload)),
-          span("f"),
-        )
+  ): Audition<
+    AuditionSelf | ClientSelf,
+    MergeState<State, ClientD>,
+    MergeMethods<External, ClientD["external"]>,
+    Event | ReturnType<typeof S.TaggedUnion<ClientD["events"]>>["Type"]
+  > => {
+    const fn = ((method: string, ...f: [any]) =>
+      Effect.fnUntraced(
+        function* (payload: any) {
+          return yield* audition
+            .fn(method)(payload)
+            .pipe(Effect.catchTag("AuditionError", () => client.fn(method)(payload)))
+        },
+        ...f,
+      )) as Fn<AuditionSelf | ClientSelf, MergeMethods<External, ClientD["external"]>>
 
     const events = audition.events.pipe(
-      Stream.catchTag("AuditionError", () =>
-        Effect.succeed(client.events).pipe(
-          Effect.tap(() => debug("AuditionStaged", { client: client.key })),
-          Stream.unwrap,
-        ),
-      ),
+      Stream.catchTag("AuditionError", () => Effect.succeed(client.events).pipe(Stream.unwrap)),
+    )
+
+    const state = audition.state.pipe(
+      Stream.catchTag("AuditionError", () => Effect.succeed(client.state).pipe(Stream.unwrap)),
     )
 
     return {
@@ -83,7 +129,8 @@ export const add: {
         return Pipeable.pipeArguments(this, arguments)
       },
       events,
-      f,
+      fn,
+      state,
     }
   },
 )