effect-cf 0.20.1 → 0.23.0

package/src/ContainerNamespace.ts

@@ -1,13 +1,17 @@
-import { Context, Data, Effect, Schema, type Layer } from "effect";
+import { Context, Data, Effect, Schema as S, type Layer } from "effect";
 
 import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
+import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedContainerNamespace = "Container namespace binding with getByName()";
 
-/** Signal accepted by Cloudflare Container instances. */
+/** Named signal accepted by Cloudflare Container instances. */
 export type ContainerSignal = "SIGKILL" | "SIGINT" | "SIGTERM";
 
+/** Named or numeric signal accepted by Container `stop()`. */
+export type ContainerStopSignal = ContainerSignal | number;
+
 /** Per-instance Container startup configuration. */
 export interface ContainerStartOptions {
   readonly envVars?: Record<string, string>;
@@ -38,15 +42,15 @@ export interface ContainerStartAndWaitForPortsOptions {
 }
 
 /** Serializable state reported by a Cloudflare Container instance. */
-export const ContainerState = Schema.Union([
-  Schema.Struct({
-    lastChange: Schema.Finite,
-    status: Schema.Literals(["running", "stopping", "stopped", "healthy"]),
+export const ContainerState = S.Union([
+  S.Struct({
+    lastChange: S.Finite,
+    status: S.Literals(["running", "stopping", "stopped", "healthy"]),
   }),
-  Schema.Struct({
-    lastChange: Schema.Finite,
-    status: Schema.Literal("stopped_with_code"),
-    exitCode: Schema.optionalKey(Schema.Int),
+  S.Struct({
+    lastChange: S.Finite,
+    status: S.Literal("stopped_with_code"),
+    exitCode: S.optionalKey(S.Int),
   }),
 ]);
 export type ContainerState = typeof ContainerState.Type;
@@ -62,8 +66,15 @@ export interface ContainerStub {
   getState(): Promise<ContainerState>;
   start(options?: ContainerStartOptions, waitOptions?: ContainerWaitOptions): Promise<void>;
   startAndWaitForPorts(options?: ContainerStartAndWaitForPortsOptions): Promise<void>;
-  stop(signal?: ContainerSignal): Promise<void>;
+  waitForPort(options: ContainerWaitOptions): Promise<number>;
+  stop(signal?: ContainerStopSignal): Promise<void>;
   destroy(): Promise<void>;
+  setAllowedHosts(hosts: Array<string>): Promise<void>;
+  setDeniedHosts(hosts: Array<string>): Promise<void>;
+  allowHost(hostname: string): Promise<void>;
+  denyHost(hostname: string): Promise<void>;
+  removeAllowedHost(hostname: string): Promise<void>;
+  removeDeniedHost(hostname: string): Promise<void>;
 }
 
 /** Native Container namespace binding shape. */
@@ -74,6 +85,11 @@ export interface ContainerNamespaceResource {
   ): ContainerStub;
 }
 
+/** Exact native stub type produced by a Container namespace binding. */
+export type ContainerStubOf<Namespace extends ContainerNamespaceResource> = ReturnType<
+  Namespace["getByName"]
+>;
+
 /** Container namespace binding metadata. */
 export interface ContainerNamespaceDefinition {
   /** Binding name as configured in `wrangler.jsonc`. */
@@ -86,11 +102,15 @@ export class ContainerOperationError extends Data.TaggedError("ContainerOperatio
   readonly instance: string;
   readonly operation: string;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Container ${this.operation} failed for binding "${this.binding}" instance "${this.instance}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 /** Effect-wrapped client for one named Container instance. */
-export interface ContainerInstanceClient {
-  readonly unsafeRaw: Effect.Effect<ContainerStub, ContainerOperationError>;
+export interface ContainerInstanceClient<Stub extends ContainerStub = ContainerStub> {
+  readonly rawUnsafe: Effect.Effect<Stub, ContainerOperationError>;
   readonly state: Effect.Effect<ContainerState, ContainerOperationError>;
   readonly fetch: (
     input: RequestInfo | URL,
@@ -103,29 +123,51 @@ export interface ContainerInstanceClient {
   readonly startAndWaitForPorts: (
     options?: ContainerStartAndWaitForPortsOptions,
   ) => Effect.Effect<void, ContainerOperationError>;
-  readonly stop: (signal?: ContainerSignal) => Effect.Effect<void, ContainerOperationError>;
+  readonly waitForPort: (
+    options: ContainerWaitOptions,
+  ) => Effect.Effect<number, ContainerOperationError>;
+  readonly stop: (signal?: ContainerStopSignal) => Effect.Effect<void, ContainerOperationError>;
   readonly destroy: Effect.Effect<void, ContainerOperationError>;
+  readonly setAllowedHosts: (
+    hosts: ReadonlyArray<string>,
+  ) => Effect.Effect<void, ContainerOperationError>;
+  readonly setDeniedHosts: (
+    hosts: ReadonlyArray<string>,
+  ) => Effect.Effect<void, ContainerOperationError>;
+  readonly allowHost: (hostname: string) => Effect.Effect<void, ContainerOperationError>;
+  readonly denyHost: (hostname: string) => Effect.Effect<void, ContainerOperationError>;
+  readonly removeAllowedHost: (hostname: string) => Effect.Effect<void, ContainerOperationError>;
+  readonly removeDeniedHost: (hostname: string) => Effect.Effect<void, ContainerOperationError>;
 }
 
 /** Effect client for a Container namespace binding. */
-export interface ContainerNamespaceClient {
+export interface ContainerNamespaceClient<
+  Namespace extends ContainerNamespaceResource = ContainerNamespaceResource,
+> {
   readonly definition: ContainerNamespaceDefinition;
   readonly getByName: (
     name: string,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
-  ) => Effect.Effect<ContainerInstanceClient, ContainerOperationError>;
+  ) => Effect.Effect<ContainerInstanceClient<ContainerStubOf<Namespace>>, ContainerOperationError>;
   readonly byName: (
     name: string,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
-  ) => ContainerInstanceClient;
-  readonly unsafeRaw: Effect.Effect<ContainerNamespaceResource>;
+  ) => ContainerInstanceClient<ContainerStubOf<Namespace>>;
+  readonly rawUnsafe: Effect.Effect<Namespace>;
 }
 
-export type ContainerNamespaceStaticClient<R> = {
+export type ContainerNamespaceStaticClient<
+  R,
+  Namespace extends ContainerNamespaceResource = ContainerNamespaceResource,
+> = {
   readonly getByName: (
     name: string,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
-  ) => Effect.Effect<ContainerInstanceClient, ContainerOperationError, R>;
+  ) => Effect.Effect<
+    ContainerInstanceClient<ContainerStubOf<Namespace>>,
+    ContainerOperationError,
+    R
+  >;
   readonly byName: (
     name: string,
     options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
@@ -142,21 +184,44 @@ export type ContainerNamespaceStaticClient<R> = {
     readonly startAndWaitForPorts: (
       options?: ContainerStartAndWaitForPortsOptions,
     ) => Effect.Effect<void, ContainerOperationError, R>;
-    readonly stop: (signal?: ContainerSignal) => Effect.Effect<void, ContainerOperationError, R>;
+    readonly waitForPort: (
+      options: ContainerWaitOptions,
+    ) => Effect.Effect<number, ContainerOperationError, R>;
+    readonly stop: (
+      signal?: ContainerStopSignal,
+    ) => Effect.Effect<void, ContainerOperationError, R>;
     readonly destroy: Effect.Effect<void, ContainerOperationError, R>;
-    readonly unsafeRaw: Effect.Effect<ContainerStub, ContainerOperationError, R>;
+    readonly setAllowedHosts: (
+      hosts: ReadonlyArray<string>,
+    ) => Effect.Effect<void, ContainerOperationError, R>;
+    readonly setDeniedHosts: (
+      hosts: ReadonlyArray<string>,
+    ) => Effect.Effect<void, ContainerOperationError, R>;
+    readonly allowHost: (hostname: string) => Effect.Effect<void, ContainerOperationError, R>;
+    readonly denyHost: (hostname: string) => Effect.Effect<void, ContainerOperationError, R>;
+    readonly removeAllowedHost: (
+      hostname: string,
+    ) => Effect.Effect<void, ContainerOperationError, R>;
+    readonly removeDeniedHost: (
+      hostname: string,
+    ) => Effect.Effect<void, ContainerOperationError, R>;
+    readonly rawUnsafe: Effect.Effect<ContainerStubOf<Namespace>, ContainerOperationError, R>;
   };
-  readonly unsafeRaw: () => Effect.Effect<ContainerNamespaceResource, never, R>;
+  readonly rawUnsafe: Effect.Effect<Namespace, never, R>;
 };
 
 export type LayerOptions = {
   readonly binding: string;
 };
 
-export interface TagClass<Self, Id extends string>
+export interface TagClass<
+  Self,
+  Id extends string,
+  Namespace extends ContainerNamespaceResource = ContainerNamespaceResource,
+>
   extends
-    Context.ServiceClass<Self, Id, ContainerNamespaceClient>,
-    ContainerNamespaceStaticClient<Self> {
+    Context.ServiceClass<Self, `effect-cf/Container/${Id}`, ContainerNamespaceClient<Namespace>>,
+    ContainerNamespaceStaticClient<Self, Namespace> {
   readonly id: Id;
   readonly layer: (
     options: LayerOptions,
@@ -184,36 +249,100 @@ const tryContainerPromise = <A>(
       }),
   });
 
-const makeInstanceClient = (
+const makeInstanceClient = <Stub extends ContainerStub>(
   definition: ContainerNamespaceDefinition,
   instance: string,
-  stub: ContainerStub,
-): ContainerInstanceClient => ({
-  unsafeRaw: Effect.succeed(stub),
-  state: tryContainerPromise(definition, instance, "state", () => stub.getState()).pipe(
-    Effect.flatMap(Schema.decodeUnknownEffect(ContainerState)),
-    Effect.mapError((cause) =>
-      cause instanceof ContainerOperationError
-        ? cause
-        : new ContainerOperationError({
-            binding: definition.binding,
-            instance,
-            operation: "state",
-            cause,
-          }),
+  stub: Stub,
+): ContainerInstanceClient<Stub> => {
+  const spanOptions = (operation: string) => ({
+    attributes: { binding: definition.binding, instance, operation },
+  });
+  const hostListOperation = (operation: "setAllowedHosts" | "setDeniedHosts") =>
+    Effect.fn(
+      `ContainerNamespace.${operation}`,
+      spanOptions(operation),
+    )(function* (hosts: ReadonlyArray<string>) {
+      return yield* tryContainerPromise(definition, instance, operation, () =>
+        stub[operation]([...hosts]),
+      );
+    });
+  const hostnameOperation = (
+    operation: "allowHost" | "denyHost" | "removeAllowedHost" | "removeDeniedHost",
+  ) =>
+    Effect.fn(
+      `ContainerNamespace.${operation}`,
+      spanOptions(operation),
+    )(function* (hostname: string) {
+      return yield* tryContainerPromise(definition, instance, operation, () =>
+        stub[operation](hostname),
+      );
+    });
+
+  return {
+    rawUnsafe: Effect.succeed(stub),
+    state: tryContainerPromise(definition, instance, "state", () => stub.getState()).pipe(
+      Effect.flatMap(S.decodeUnknownEffect(ContainerState)),
+      Effect.mapError((cause) =>
+        cause instanceof ContainerOperationError
+          ? cause
+          : new ContainerOperationError({
+              binding: definition.binding,
+              instance,
+              operation: "state",
+              cause,
+            }),
+      ),
+      Effect.withSpan("ContainerNamespace.state", spanOptions("state")),
     ),
-  ),
-  fetch: (input, init) =>
-    tryContainerPromise(definition, instance, "fetch", () => stub.fetch(input, init)),
-  start: (options, waitOptions) =>
-    tryContainerPromise(definition, instance, "start", () => stub.start(options, waitOptions)),
-  startAndWaitForPorts: (options) =>
-    tryContainerPromise(definition, instance, "startAndWaitForPorts", () =>
-      stub.startAndWaitForPorts(options),
+    fetch: Effect.fn(
+      "ContainerNamespace.fetch",
+      spanOptions("fetch"),
+    )(function* (input: RequestInfo | URL, init?: RequestInit) {
+      return yield* tryContainerPromise(definition, instance, "fetch", () =>
+        stub.fetch(input, init),
+      );
+    }),
+    start: Effect.fn(
+      "ContainerNamespace.start",
+      spanOptions("start"),
+    )(function* (options?: ContainerStartOptions, waitOptions?: ContainerWaitOptions) {
+      return yield* tryContainerPromise(definition, instance, "start", () =>
+        stub.start(options, waitOptions),
+      );
+    }),
+    startAndWaitForPorts: Effect.fn(
+      "ContainerNamespace.startAndWaitForPorts",
+      spanOptions("startAndWaitForPorts"),
+    )(function* (options?: ContainerStartAndWaitForPortsOptions) {
+      return yield* tryContainerPromise(definition, instance, "startAndWaitForPorts", () =>
+        stub.startAndWaitForPorts(options),
+      );
+    }),
+    waitForPort: Effect.fn(
+      "ContainerNamespace.waitForPort",
+      spanOptions("waitForPort"),
+    )(function* (options: ContainerWaitOptions) {
+      return yield* tryContainerPromise(definition, instance, "waitForPort", () =>
+        stub.waitForPort(options),
+      );
+    }),
+    stop: Effect.fn(
+      "ContainerNamespace.stop",
+      spanOptions("stop"),
+    )(function* (signal?: ContainerStopSignal) {
+      return yield* tryContainerPromise(definition, instance, "stop", () => stub.stop(signal));
+    }),
+    destroy: tryContainerPromise(definition, instance, "destroy", () => stub.destroy()).pipe(
+      Effect.withSpan("ContainerNamespace.destroy", spanOptions("destroy")),
     ),
-  stop: (signal) => tryContainerPromise(definition, instance, "stop", () => stub.stop(signal)),
-  destroy: tryContainerPromise(definition, instance, "destroy", () => stub.destroy()),
-});
+    setAllowedHosts: hostListOperation("setAllowedHosts"),
+    setDeniedHosts: hostListOperation("setDeniedHosts"),
+    allowHost: hostnameOperation("allowHost"),
+    denyHost: hostnameOperation("denyHost"),
+    removeAllowedHost: hostnameOperation("removeAllowedHost"),
+    removeDeniedHost: hostnameOperation("removeDeniedHost"),
+  };
+};
 
 export const isContainerNamespaceResource = (value: unknown): value is ContainerNamespaceResource =>
   typeof value === "object" &&
@@ -222,13 +351,22 @@ export const isContainerNamespaceResource = (value: unknown): value is Container
 
 export const makeClient =
   (definition: ContainerNamespaceDefinition) =>
-  (namespace: ContainerNamespaceResource): ContainerNamespaceClient => {
+  <Namespace extends ContainerNamespaceResource>(
+    namespace: Namespace,
+  ): ContainerNamespaceClient<Namespace> => {
     const getByName = (
       name: string,
       options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
     ) =>
       Effect.try({
-        try: () => makeInstanceClient(definition, name, namespace.getByName(name, options)),
+        try: () =>
+          makeInstanceClient(
+            definition,
+            name,
+            // getByName has a single call signature, so its return type is
+            // exactly the namespace's stub type.
+            namespace.getByName(name, options) as ContainerStubOf<Namespace>,
+          ),
         catch: (cause) =>
           new ContainerOperationError({
             binding: definition.binding,
@@ -241,19 +379,31 @@ export const makeClient =
     const byName = (
       name: string,
       options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
-    ): ContainerInstanceClient => {
+    ): ContainerInstanceClient<ContainerStubOf<Namespace>> => {
       const instance = getByName(name, options);
 
       return {
-        unsafeRaw: Effect.flatMap(instance, (client) => client.unsafeRaw),
+        rawUnsafe: Effect.flatMap(instance, (client) => client.rawUnsafe),
         state: Effect.flatMap(instance, (client) => client.state),
         fetch: (input, init) => Effect.flatMap(instance, (client) => client.fetch(input, init)),
         start: (startOptions, waitOptions) =>
           Effect.flatMap(instance, (client) => client.start(startOptions, waitOptions)),
         startAndWaitForPorts: (startOptions) =>
           Effect.flatMap(instance, (client) => client.startAndWaitForPorts(startOptions)),
+        waitForPort: (waitOptions) =>
+          Effect.flatMap(instance, (client) => client.waitForPort(waitOptions)),
         stop: (signal) => Effect.flatMap(instance, (client) => client.stop(signal)),
         destroy: Effect.flatMap(instance, (client) => client.destroy),
+        setAllowedHosts: (hosts) =>
+          Effect.flatMap(instance, (client) => client.setAllowedHosts(hosts)),
+        setDeniedHosts: (hosts) =>
+          Effect.flatMap(instance, (client) => client.setDeniedHosts(hosts)),
+        allowHost: (hostname) => Effect.flatMap(instance, (client) => client.allowHost(hostname)),
+        denyHost: (hostname) => Effect.flatMap(instance, (client) => client.denyHost(hostname)),
+        removeAllowedHost: (hostname) =>
+          Effect.flatMap(instance, (client) => client.removeAllowedHost(hostname)),
+        removeDeniedHost: (hostname) =>
+          Effect.flatMap(instance, (client) => client.removeDeniedHost(hostname)),
       };
     };
 
@@ -261,17 +411,25 @@ export const makeClient =
       definition,
       getByName,
       byName,
-      unsafeRaw: Effect.succeed(namespace),
+      rawUnsafe: Effect.succeed(namespace),
     };
   };
 
-export const layer = <Self>(
-  tag: Context.Service<Self, ContainerNamespaceClient>,
+export const layer = <Self, Namespace extends ContainerNamespaceResource>(
+  tag: Context.Service<Self, ContainerNamespaceClient<Namespace>>,
   definition: ContainerNamespaceDefinition,
 ) =>
-  Binding.layer(tag, definition.binding, isContainerNamespaceResource, makeClient(definition), {
-    expected: expectedContainerNamespace,
-  });
+  Binding.layer(
+    tag,
+    definition.binding,
+    // Runtime validation stays structural; the exact namespace type is
+    // asserted by the consumer's binding declaration, like env typing.
+    isContainerNamespaceResource as (value: unknown) => value is Namespace,
+    makeClient(definition),
+    {
+      expected: expectedContainerNamespace,
+    },
+  );
 
 export const make = <Id extends string>(id: Id) => Tag<ContainerNamespaceService<Id>>()<Id>(id);
 
@@ -286,20 +444,21 @@ export interface ContainerNamespaceService<Id extends string> {
 
 /** Creates a typed Effect service for a Cloudflare Container namespace. */
 export const Tag =
-  <Self>() =>
+  <Self, Namespace extends ContainerNamespaceResource = ContainerNamespaceResource>() =>
   <Id extends string>(id: Id) => {
-    const tag = Context.Service<Self, ContainerNamespaceClient>()(id);
+    const tag = Context.Service<Self, ContainerNamespaceClient<Namespace>>()(
+      `effect-cf/Container/${id}` as const,
+    );
     const makeLayer = (definition: LayerOptions) => layer(tag, definition);
 
-    const getByName = (
+    const getByName = Effect.fnUntraced(function* (
       name: string,
       options?: globalThis.DurableObjectNamespaceGetDurableObjectOptions,
-    ) =>
-      Effect.gen(function* () {
-        const namespace = yield* tag;
+    ) {
+      const namespace = yield* tag;
 
-        return yield* namespace.getByName(name, options);
-      });
+      return yield* namespace.getByName(name, options);
+    });
 
     const byName = (
       name: string,
@@ -316,25 +475,37 @@ export const Tag =
         Effect.flatMap(getByName(name, options), (instance) =>
           instance.startAndWaitForPorts(startOptions),
         ),
-      stop: (signal?: ContainerSignal) =>
+      waitForPort: (waitOptions: ContainerWaitOptions) =>
+        Effect.flatMap(getByName(name, options), (instance) => instance.waitForPort(waitOptions)),
+      stop: (signal?: ContainerStopSignal) =>
         Effect.flatMap(getByName(name, options), (instance) => instance.stop(signal)),
       destroy: Effect.flatMap(getByName(name, options), (instance) => instance.destroy),
-      unsafeRaw: Effect.flatMap(getByName(name, options), (instance) => instance.unsafeRaw),
+      setAllowedHosts: (hosts: ReadonlyArray<string>) =>
+        Effect.flatMap(getByName(name, options), (instance) => instance.setAllowedHosts(hosts)),
+      setDeniedHosts: (hosts: ReadonlyArray<string>) =>
+        Effect.flatMap(getByName(name, options), (instance) => instance.setDeniedHosts(hosts)),
+      allowHost: (hostname: string) =>
+        Effect.flatMap(getByName(name, options), (instance) => instance.allowHost(hostname)),
+      denyHost: (hostname: string) =>
+        Effect.flatMap(getByName(name, options), (instance) => instance.denyHost(hostname)),
+      removeAllowedHost: (hostname: string) =>
+        Effect.flatMap(getByName(name, options), (instance) =>
+          instance.removeAllowedHost(hostname),
+        ),
+      removeDeniedHost: (hostname: string) =>
+        Effect.flatMap(getByName(name, options), (instance) => instance.removeDeniedHost(hostname)),
+      rawUnsafe: Effect.flatMap(getByName(name, options), (instance) => instance.rawUnsafe),
     });
 
-    const unsafeRaw = Effect.fn(function* () {
-      const namespace = yield* tag;
-
-      return yield* namespace.unsafeRaw;
-    });
+    const rawUnsafe = Effect.flatMap(tag, (namespace) => namespace.rawUnsafe);
 
     return Object.assign(tag, {
       id,
       layer: makeLayer,
       getByName,
       byName,
-      unsafeRaw,
-    }) as TagClass<Self, Id>;
+      rawUnsafe,
+    }) as TagClass<Self, Id, Namespace>;
   };
 
 export const ContainerNamespace = Tag;

package/src/D1.ts

@@ -1,9 +1,13 @@
 import { D1Client } from "@effect/sql-d1";
-import { Effect, Layer } from "effect";
+import { Effect, Layer, type Config } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
 
 import * as Binding from "./Binding";
+import type { WorkerEnvironment } from "./Environment";
 
-const TypeId = "effect-cf/D1" as const;
+const TypeId = "~effect-cf/D1" as const;
+
+export type TypeId = typeof TypeId;
 const expectedD1Database = "D1 database binding with prepare(), batch(), and exec()";
 
 /** Typed D1 binding definition. */
@@ -66,7 +70,13 @@ export const Service =
       expected: expectedD1Database,
     });
 
-    const sqlLayer = (options?: D1SqlLayerOptions) =>
+    const sqlLayer = (
+      options?: D1SqlLayerOptions,
+    ): Layer.Layer<
+      D1Client.D1Client | SqlClient.SqlClient,
+      Config.ConfigError | Binding.BindingNotFoundError | Binding.BindingValidationError,
+      WorkerEnvironment
+    > =>
       Layer.unwrap(
         Effect.gen(function* () {
           const db = yield* tag;