@visiolab/effect-firebase-functions 0.0.0-stage → 0.3.0

package/src/internal/documentTrigger.ts

@@ -0,0 +1,188 @@
+/**
+ * The Document Trigger kind's runtime: serves one Document Trigger as an
+ * `onDocument*` export.
+ *
+ * @internal
+ */
+import { Cause, Effect, Exit, type Layer, Option } from "effect";
+import * as AdminFirestoreValue from "@visiolab/effect-firebase-admin/firestore/AdminFirestoreValue";
+import * as Collection from "@visiolab/effect-firebase/firestore/Collection";
+import * as DocumentSnapshot from "@visiolab/effect-firebase/firestore/DocumentSnapshot";
+import * as DocumentTrigger from "@visiolab/effect-firebase/functions/DocumentTrigger";
+import type * as FunctionGroup from "@visiolab/effect-firebase/functions/FunctionGroup";
+import * as Firestore from "firebase-functions/v2/firestore";
+import * as Member from "./member.ts";
+import * as Runtime from "./runtime.ts";
+
+/**
+ * The typed reference of the document an event is about, from its path
+ * relative to the database's `documents/`. A path outside the trigger's
+ * collection can't come from its own path pattern, so it is a defect.
+ */
+const refOf = (trigger: DocumentTrigger.Any, path: string) =>
+  Option.match(Collection.fromPath(trigger.collection, path), {
+    onNone: () =>
+      Effect.die(
+        new Error(
+          `The document "${path}" is not in the collection of the trigger "${trigger.name}"`,
+        ),
+      ),
+    onSome: Effect.succeed,
+  });
+
+/**
+ * An existing Document Snapshot at `ref` of the Admin SDK's snapshot, its
+ * data read into Firestore Values as a read does. Data that isn't a Firestore
+ * Value, such as a vector, is a defect.
+ */
+const existingOf = (
+  ref: Collection.DocumentReference<Collection.Any>,
+  snapshot: Firestore.DocumentSnapshot | undefined,
+): Effect.Effect<DocumentSnapshot.Existing<Collection.Any>> =>
+  snapshot === undefined
+    ? Effect.die(new Error(`The event of "${ref.path}" carries no document`))
+    : Effect.map(
+        Effect.orDie(Effect.fromResult(AdminFirestoreValue.fromAdmin(snapshot.data()))),
+        (raw) => DocumentSnapshot.existing(ref, raw),
+      );
+
+/**
+ * The document of an event that hands over one, as an existing Document
+ * Snapshot: the created one, or the deleted one as it was just before.
+ */
+const snapshotOf = (
+  ref: Collection.DocumentReference<Collection.Any>,
+  snapshot: Firestore.QueryDocumentSnapshot | undefined,
+) => Effect.map(existingOf(ref, snapshot), (snapshot) => ({ snapshot }));
+
+/**
+ * A Document Snapshot at `ref` of a side of a write: `Missing` for the side
+ * that doesn't exist, as the Admin SDK marks it with `exists`.
+ */
+const sideOf = (
+  ref: Collection.DocumentReference<Collection.Any>,
+  snapshot: Firestore.DocumentSnapshot,
+): Effect.Effect<DocumentSnapshot.DocumentSnapshot<Collection.Any>> =>
+  snapshot.exists ? existingOf(ref, snapshot) : Effect.succeed(DocumentSnapshot.missing(ref));
+
+/**
+ * Both sides of a change, each read with `side`: both existing for an update,
+ * and either one missing for a write. An event without its change is a defect.
+ */
+const changeOf =
+  <S, A>(
+    side: (ref: Collection.DocumentReference<Collection.Any>, snapshot: S) => Effect.Effect<A>,
+  ) =>
+  (ref: Collection.DocumentReference<Collection.Any>, change: Firestore.Change<S> | undefined) =>
+    change === undefined
+      ? Effect.die(new Error(`The event of "${ref.path}" carries no change`))
+      : Effect.all({ before: side(ref, change.before), after: side(ref, change.after) });
+
+/**
+ * The conversion of what an `onDocument*` provider hands over into the core
+ * event of a trigger: `read` reads the event's data at the document's typed
+ * reference, and `make` builds the core event from that and the CloudEvent's
+ * `id` and `time`.
+ */
+const conversion =
+  <Data, Fields>(
+    read: (ref: Collection.DocumentReference<Collection.Any>, data: Data) => Effect.Effect<Fields>,
+    make: (input: Fields & { readonly id: string; readonly time: string }) => unknown,
+  ) =>
+  (trigger: DocumentTrigger.Any, event: Firestore.FirestoreEvent<Data>) =>
+    Effect.flatMap(refOf(trigger, event.document), (ref) =>
+      Effect.map(read(ref, event.data), (fields) =>
+        make({ ...fields, id: event.id, time: event.time }),
+      ),
+    );
+
+const createdEvent = conversion(snapshotOf, DocumentTrigger.createdEvent);
+const deletedEvent = conversion(snapshotOf, DocumentTrigger.deletedEvent);
+const updatedEvent = conversion(changeOf(existingOf), DocumentTrigger.updatedEvent);
+const writtenEvent = conversion(changeOf(sideOf), DocumentTrigger.writtenEvent);
+
+/**
+ * Logs the Cause of a failed event or Layer build in the event's span.
+ */
+const logFailure = (message: string) => (cause: Cause.Cause<unknown>) =>
+  Effect.logError(message, cause);
+
+/**
+ * `DocumentTrigger.serve` of one trigger, with its requirements erased, since
+ * the public signatures check that `live` meets them.
+ */
+type Serve = Effect.Effect<(event: unknown) => Effect.Effect<void, unknown>, never, unknown>;
+
+/**
+ * What an `onDocument*` provider returns, by the change it runs on.
+ *
+ * @internal
+ */
+export type Export =
+  | ReturnType<typeof Firestore.onDocumentCreated>
+  | ReturnType<typeof Firestore.onDocumentUpdated>
+  | ReturnType<typeof Firestore.onDocumentWritten>;
+
+/**
+ * The export of `trigger` in `group`, or in no group: the `onDocument*`
+ * export of its change (`onDocumentCreated`, `onDocumentDeleted`,
+ * `onDocumentUpdated` or `onDocumentWritten`) on the `(default)` database, at
+ * the path pattern of the trigger's collection, that converts each event and
+ * runs it through `DocumentTrigger.serve`. It builds `live` on its own first
+ * event. A failed event, or a failed build, is logged and thrown, so Firebase
+ * delivers it again when `retry` is set.
+ *
+ * @internal
+ */
+export const deploy = <R, E>(
+  group: FunctionGroup.Any | undefined,
+  trigger: DocumentTrigger.Any,
+  live: Layer.Layer<R, E>,
+  options: object = {},
+): Export => {
+  const deployment = Member.call(group, trigger, DocumentTrigger.deployment);
+  const serve = Member.call<Serve>(group, trigger, DocumentTrigger.serve);
+  const run = Runtime.make(live, {
+    span: `DocumentTrigger.${deployment.name}`,
+    attributes: { "faas.name": deployment.name, "faas.trigger": "datasource" },
+    onBuildFailure: logFailure("The Layer of a Document Trigger failed to build"),
+  });
+  /** The raw handler that converts each event with `convert` and serves it. */
+  const handler =
+    <Data>(
+      convert: (
+        trigger: DocumentTrigger.Any,
+        event: Firestore.FirestoreEvent<Data>,
+      ) => Effect.Effect<unknown>,
+    ) =>
+    async (event: Firestore.FirestoreEvent<Data>) => {
+      const exit = await run(
+        serve.pipe(
+          Effect.flatMap((handle) =>
+            Effect.flatMap(convert(trigger, event), (input) => handle(input)),
+          ),
+          // Logged with the services of `live`, so a logger it provides is used.
+          Effect.onError(logFailure("A Document Trigger failed")),
+        ),
+      );
+      if (Exit.isFailure(exit)) throw Cause.squash(exit.cause);
+    };
+  // After `options`, so a caller that passes event filters past the public
+  // types can't move the trigger to another path, database or namespace.
+  const providerOptions = {
+    ...options,
+    document: deployment.document,
+    database: "(default)",
+    namespace: "(default)",
+  };
+  switch (trigger.event) {
+    case "created":
+      return Firestore.onDocumentCreated(providerOptions, handler(createdEvent));
+    case "deleted":
+      return Firestore.onDocumentDeleted(providerOptions, handler(deletedEvent));
+    case "updated":
+      return Firestore.onDocumentUpdated(providerOptions, handler(updatedEvent));
+    case "written":
+      return Firestore.onDocumentWritten(providerOptions, handler(writtenEvent));
+  }
+};

package/src/internal/kinds.ts

@@ -0,0 +1,36 @@
+/**
+ * Where `Functions.make` and `Functions.group` dispatch on a Function's kind.
+ * A new kind adds its runtime's `deploy` here, and its types to the
+ * kind-dispatched types of `Functions.ts` (`Export`, `Options`, `Services`).
+ *
+ * @internal
+ */
+import type { Layer } from "effect";
+import type * as Callable from "@visiolab/effect-firebase/functions/Callable";
+import type * as DocumentTrigger from "@visiolab/effect-firebase/functions/DocumentTrigger";
+import type * as FirebaseFunction from "@visiolab/effect-firebase/functions/FirebaseFunction";
+import type * as FunctionGroup from "@visiolab/effect-firebase/functions/FunctionGroup";
+import * as callable from "./callable.ts";
+import * as documentTrigger from "./documentTrigger.ts";
+
+/**
+ * The export of `fn` in `group`, or in no group, from its kind's runtime.
+ * `options` are the member's own, typed by kind in the public signatures.
+ *
+ * @internal
+ */
+export const deploy = <R, E>(
+  group: FunctionGroup.Any | undefined,
+  fn: FirebaseFunction.Any,
+  live: Layer.Layer<R, E>,
+  options: object | undefined,
+): unknown => {
+  switch (fn.kind) {
+    case "Callable":
+      return callable.deploy(group, fn as Callable.Any, live, options);
+    case "DocumentTrigger":
+      return documentTrigger.deploy(group, fn as DocumentTrigger.Any, live, options);
+    default:
+      throw new Error(`Functions can't deploy "${fn.name}": its kind "${fn.kind}" is unknown`);
+  }
+};

package/src/internal/member.ts

@@ -0,0 +1,21 @@
+/**
+ * How a kind's runtime calls the core functions that take a Function alone or
+ * a Function Group and a member's name, such as `deployment` and `serve`.
+ *
+ * @internal
+ */
+import type * as FirebaseFunction from "@visiolab/effect-firebase/functions/FirebaseFunction";
+import type * as FunctionGroup from "@visiolab/effect-firebase/functions/FunctionGroup";
+
+/**
+ * Calls `api` with `fn` alone, or with `group` and the name of `fn` when it is
+ * a member of `group`. The kind's public signatures already checked that `fn`
+ * is of the kind `api` takes, so its arguments are erased.
+ *
+ * @internal
+ */
+export const call = <A>(
+  group: FunctionGroup.Any | undefined,
+  fn: FirebaseFunction.Any,
+  api: (...args: ReadonlyArray<never>) => A,
+): A => (group === undefined ? api(fn as never) : api(group as never, fn.name as never));

package/src/internal/runtime.ts

@@ -0,0 +1,110 @@
+/**
+ * What every kind of Function runs an event or a call under: the lazy,
+ * memoized build of its Layer, its server span, its Tracer and its logs.
+ *
+ * A kind's runtime turns what `firebase-functions` hands over into the input
+ * of its core `serve`, and passes that to {@link make}'s run function, which
+ * does the rest.
+ *
+ * @internal
+ */
+import { type Cause, Context, Effect, Exit, Layer, Logger, Scope } from "effect";
+import * as CloudLogging from "../logger/CloudLogging.ts";
+import { DeferredTracer, externalParent } from "./serverSpan.ts";
+
+/**
+ * The memo map and scope every Layer of this process is built in, so a Layer
+ * that several exports share is built once. The scope is never closed:
+ * functions-framework exits the process without waiting for finalizers.
+ */
+const memoMap = Layer.makeMemoMapUnsafe();
+const scope = Scope.makeUnsafe();
+
+/**
+ * Builds `live` on the first event, and hands every later event the same
+ * services. Concurrent first events share one build. The build runs under the
+ * span and Tracer of the event that starts it, so it nests under that event.
+ *
+ * A failed build fails the event and is tried again on the next one. A Layer
+ * that fails closes the scope it was built in, which drops its failed entries
+ * from the memo map, so the retry builds anew.
+ */
+const lazyContext = <R, E>(live: Layer.Layer<R, E>) => {
+  let pending: Promise<Exit.Exit<Context.Context<R>, E>> | undefined;
+  return Effect.flatMap(Effect.context<never>(), (caller) => {
+    pending ??= Effect.runPromiseExit(
+      Layer.buildWithMemoMap(live, memoMap, scope).pipe(Effect.provideContext(caller)),
+    ).then((exit) => {
+      if (Exit.isFailure(exit)) pending = undefined;
+      return exit;
+    });
+    const attempt = pending;
+    return Effect.flatten(Effect.promise(() => attempt));
+  });
+};
+
+/**
+ * How one export runs each event or call.
+ *
+ * @internal
+ */
+export interface Options {
+  /** The name of the `kind: "server"` span each event or call runs in. */
+  readonly span: string;
+  /** The attributes of that span. */
+  readonly attributes: Readonly<Record<string, unknown>>;
+  /**
+   * Logs the Cause of a Layer that failed to build, in the span of the event
+   * or call that built it.
+   */
+  readonly onBuildFailure: (cause: Cause.Cause<unknown>) => Effect.Effect<void>;
+}
+
+/**
+ * The run function of one export: it builds `live` on the export's first
+ * event or call, so a worker that serves one export builds nothing for the
+ * others, and runs each `body` with the services of `live` provided.
+ *
+ * The run happens in a `kind: "server"` span, parented on the trace context
+ * Firebase read from the event or request. Its spans go to the Tracer of
+ * `live`, its logs go through `CloudLogging.layer` unless `live` provides a
+ * logger, and logs from before `live` is built wait until the spans have
+ * their final ids.
+ *
+ * Read the trace context synchronously, at the start of the SDK's handler:
+ * call the run function there.
+ *
+ * @internal
+ */
+export const make = <R, E>(live: Layer.Layer<R, E>, options: Options) => {
+  const context = lazyContext(live);
+  const spanOptions = { kind: "server", attributes: options.attributes } as const;
+  return <A>(
+    body: Effect.Effect<A, unknown, unknown>,
+    signal?: AbortSignal,
+  ): Promise<Exit.Exit<A, unknown>> => {
+    const parent = externalParent();
+    const deferred = new DeferredTracer();
+    return Effect.runPromiseExit(
+      Effect.gen(function* () {
+        const services = yield* context.pipe(
+          // With no services to take a Tracer from, the run's spans and held
+          // logs go to the native Tracer, so the failure is logged in one trace.
+          Effect.onError(() => Effect.sync(() => deferred.attach(Context.empty()))),
+          Effect.onError(options.onBuildFailure),
+        );
+        deferred.attach(services as Context.Context<never>);
+        // The public signatures check that `live` provides what `body` needs.
+        return yield* Effect.provideContext(body, services as Context.Context<any>);
+      }).pipe(
+        Effect.withSpan(options.span, { ...spanOptions, parent }),
+        // Logs from before `live` is built wait for the spans' real ids.
+        Effect.updateService(Logger.CurrentLoggers, (loggers) => deferred.holdLogs(loggers)),
+        // Beneath `live`: a logger that `live` provides replaces this one.
+        Effect.provide(CloudLogging.layer),
+        Effect.withTracer(deferred.tracer),
+      ),
+      signal === undefined ? undefined : { signal },
+    );
+  };
+};

package/src/internal/serverSpan.ts

@@ -0,0 +1,203 @@
+/** @internal */
+import { Context, Logger, Option, Tracer, type Exit, type Fiber } from "effect";
+import { traceContext } from "firebase-functions/v2";
+
+/**
+ * The parent of a call's server span: the trace context `firebase-functions`
+ * read from the request's headers, the `X-Cloud-Trace-Context` header winning
+ * over `traceparent`. Read it synchronously at the start of the call, before
+ * any fiber runs: Effect's scheduler may later run under another request's
+ * async store. `undefined` when the request carried none, as in the emulator.
+ *
+ * @internal
+ */
+export const externalParent = (): Tracer.ExternalSpan | undefined => {
+  const store = traceContext.getStore();
+  if (store === undefined) return undefined;
+  return Tracer.externalSpan({
+    traceId: store.traceId,
+    // The Cloud header's decimal span id reaches us as unpadded hex.
+    spanId: store.parentId.padStart(16, "0"),
+    sampled: store.sample,
+  });
+};
+
+type SpanOptions = Parameters<Tracer.Tracer["span"]>[0];
+
+/**
+ * A span opened before the Tracer of `Live` is known. It records what happens
+ * to it, and replays that onto the real span once {@link DeferredTracer.attach}
+ * creates it. From then on it forwards everything.
+ */
+class DeferredSpan implements Tracer.Span {
+  readonly _tag = "Span";
+  readonly name: string;
+  readonly parent: Option.Option<Tracer.AnySpan>;
+  readonly annotations: Context.Context<never>;
+  readonly kind: Tracer.SpanKind;
+  readonly sampled: boolean;
+  readonly options: SpanOptions;
+  real: Tracer.Span | undefined;
+  // What happened before `real` existed, in order.
+  private readonly calls: Array<(span: Tracer.Span) => void> = [];
+  private readonly pendingAttributes = new Map<string, unknown>();
+  private readonly pendingLinks: Array<Tracer.SpanLink>;
+  private pendingStatus: Tracer.SpanStatus;
+  private provisional: { traceId: string; spanId: string } | undefined;
+
+  constructor(options: SpanOptions) {
+    this.options = options;
+    this.name = options.name;
+    this.parent = options.parent;
+    this.annotations = options.annotations;
+    this.kind = options.kind;
+    this.sampled = options.sampled;
+    this.pendingLinks = [...options.links];
+    this.pendingStatus = { _tag: "Started", startTime: options.startTime };
+  }
+
+  // Read before `attach` only by a Tracer that `Live` provides to its own
+  // Layers: such a span joins the trace, but its parent's span id is one no
+  // exporter sees.
+  private get ids() {
+    if (this.provisional === undefined) {
+      const native = new Tracer.NativeSpan({ ...this.options, links: [] });
+      this.provisional = { traceId: native.traceId, spanId: native.spanId };
+    }
+    return this.provisional;
+  }
+
+  get traceId() {
+    return this.real?.traceId ?? this.ids.traceId;
+  }
+
+  get spanId() {
+    return this.real?.spanId ?? this.ids.spanId;
+  }
+
+  get status() {
+    return this.real?.status ?? this.pendingStatus;
+  }
+
+  get attributes() {
+    return this.real?.attributes ?? this.pendingAttributes;
+  }
+
+  get links() {
+    return this.real?.links ?? this.pendingLinks;
+  }
+
+  end(endTime: bigint, exit: Exit.Exit<unknown, unknown>) {
+    if (this.real !== undefined) return this.real.end(endTime, exit);
+    if (this.pendingStatus._tag === "Ended") return;
+    this.pendingStatus = { _tag: "Ended", startTime: this.pendingStatus.startTime, endTime, exit };
+  }
+
+  attribute(key: string, value: unknown) {
+    if (this.real !== undefined) return this.real.attribute(key, value);
+    this.pendingAttributes.set(key, value);
+  }
+
+  event(name: string, startTime: bigint, attributes?: Record<string, unknown>) {
+    if (this.real !== undefined) return this.real.event(name, startTime, attributes);
+    this.calls.push((span) => span.event(name, startTime, attributes));
+  }
+
+  addLinks(links: ReadonlyArray<Tracer.SpanLink>) {
+    if (this.real !== undefined) return this.real.addLinks(links);
+    this.calls.push((span) => span.addLinks(links));
+  }
+
+  /** Opens the real span on `tracer` and replays onto it what happened so far. */
+  attach(tracer: Tracer.Tracer) {
+    const parent = Option.map(this.parent, (parent) =>
+      parent instanceof DeferredSpan ? (parent.real ?? parent) : parent,
+    );
+    const real = tracer.span({ ...this.options, parent, links: this.pendingLinks });
+    for (const [key, value] of this.pendingAttributes) real.attribute(key, value);
+    for (const call of this.calls) call(real);
+    if (this.pendingStatus._tag === "Ended") {
+      real.end(this.pendingStatus.endTime, this.pendingStatus.exit);
+    }
+    this.real = real;
+  }
+}
+
+/**
+ * The Tracer a call starts under. A call's server span opens before `Live` is
+ * built, and so before its Tracer is known, so that a first call's Layer
+ * build nests under it. This Tracer defers the spans opened until then, and
+ * {@link DeferredTracer.attach} hands them to the Tracer of `Live`, which
+ * exports them with their original times and parents.
+ *
+ * @internal
+ */
+export class DeferredTracer {
+  private readonly deferred: Array<DeferredSpan> = [];
+  private readonly held: Array<() => void> = [];
+  private real: Tracer.Tracer | undefined;
+
+  /**
+   * Wraps each of `loggers` so that an entry logged before {@link attach}
+   * is held, and logged on `attach`, once the spans it was logged under have
+   * their real ids. A logger reads the trace of the current span, and a
+   * deferred span's ids before `attach` are ones no exporter sees.
+   *
+   * The tracer logger isn't held: it writes onto the span itself, which a
+   * deferred span already replays.
+   */
+  holdLogs(
+    loggers: ReadonlySet<Logger.Logger<unknown, any>>,
+  ): ReadonlySet<Logger.Logger<unknown, any>> {
+    return new Set(
+      Array.from(loggers, (logger) =>
+        logger === Logger.tracerLogger
+          ? logger
+          : Logger.make<unknown, unknown>((options) => {
+              if (this.real !== undefined) return logger.log(options);
+              const held = { ...options, fiber: snapshot(options.fiber) };
+              this.held.push(() => logger.log(held));
+            }),
+      ),
+    );
+  }
+
+  readonly tracer: Tracer.Tracer = Tracer.make({
+    span: (options) => {
+      if (this.real !== undefined) return this.real.span(options);
+      const span = new DeferredSpan(options);
+      this.deferred.push(span);
+      return span;
+    },
+  });
+
+  /**
+   * Hands every span opened so far to the Tracer that `services` provide, the
+   * native one when they provide none, in the order they were opened, so that
+   * each parent exists before its children. Then logs the entries
+   * {@link holdLogs} held, in the order they were logged.
+   *
+   * Attach with no services when `Live` failed to build, so the spans and
+   * logs of the failed call still get ids of one trace.
+   */
+  attach(services: Context.Context<never>) {
+    if (this.real !== undefined) return;
+    this.real = Context.get(services, Tracer.Tracer);
+    for (const span of this.deferred) span.attach(this.real);
+    this.deferred.length = 0;
+    for (const log of this.held) log();
+    this.held.length = 0;
+  }
+}
+
+/**
+ * `fiber` as it is now: what a logger reads from it later, such as the log
+ * annotations and the current span, stays what it was when the entry was
+ * logged. Both are derived from the fiber's context, which never changes in
+ * place, only gets replaced.
+ */
+const snapshot = <A, E>(fiber: Fiber.Fiber<A, E>): Fiber.Fiber<A, E> =>
+  Object.create(fiber, {
+    context: { value: fiber.context },
+    cache: { value: fiber.cache },
+  }) as Fiber.Fiber<A, E>;