@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/src/functions/FirebaseFunction.ts

@@ -0,0 +1,96 @@
+/**
+ * Functions: what every kind of server function shares, whatever runs it.
+ *
+ * A Function is declared once by its name and what runs it. A
+ * {@link Callable.Callable} is one kind of Function, run by a call from the
+ * client. Each kind has a module of its own, which owns its declaration, its
+ * handler and how it serves. This module holds only what they share: the
+ * kind, the name, and the {@link Handler} key a handler is provided under.
+ *
+ * Functions are deployed with `Functions.make` for a Function in no group,
+ * and `Functions.group` for the members of a
+ * {@link FunctionGroup.FunctionGroup}, from `@visiolab/effect-firebase-functions`.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+import type * as internal from "./internal/firebaseFunction.ts";
+
+/**
+ * A Function: a server function's kind and its name.
+ *
+ * **Details**
+ *
+ * The name is the Function's identity. A Function in no group is deployed
+ * under its name, and a member of a group under `<group>-<name>`. It is a
+ * literal type that exports and group members are keyed on.
+ *
+ * The kind says what runs the Function, such as `"Callable"`, and decides how
+ * it is served and deployed.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface FirebaseFunction<out Kind extends string, out Name extends string> {
+  /** What runs the Function, such as `"Callable"`. */
+  readonly kind: Kind;
+  /** The Function's name, which a Function in no group is deployed under. */
+  readonly name: Name;
+}
+
+/**
+ * Any {@link FirebaseFunction}, whatever its kind and name.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Any extends FirebaseFunction<string, string> {}
+
+/**
+ * Marks the {@link Handler} of a Function in no group.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface NoGroup {
+  readonly [internal.NoGroupTypeId]: typeof internal.NoGroupTypeId;
+}
+
+/**
+ * The service that holds the handler of the Function `Name`, as served in
+ * `Group`, whatever its kind.
+ *
+ * **Details**
+ *
+ * A handler is keyed by its group and its name, so the handler of `greet` in
+ * no group is `Handler<NoGroup, "greet">`, and that of `create` in the group
+ * `users` is `Handler<"users", "create">`. A Layer that serves a Function must
+ * provide its handler under exactly that key. Each kind's `toLayer`, such as
+ * {@link Callable.toLayer}, builds such a Layer.
+ *
+ * @see {@link HandlerFor} for the handler of a Function in no group
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Handler<Group, Name extends string> {
+  readonly [internal.HandlerTypeId]: {
+    readonly group: Group;
+    readonly name: Name;
+  };
+}
+
+/**
+ * The {@link Handler} of a Function in no group.
+ *
+ * @see {@link Handler} for the handler of a member of a group
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type HandlerFor<F extends Any> = Handler<NoGroup, F["name"]>;

package/src/functions/FunctionGroup.ts

@@ -0,0 +1,225 @@
+/**
+ * Function Groups: named sets of Functions of any kind that deploy under the
+ * group's name as a prefix.
+ *
+ * A member `create` of the group `users` deploys as `users-create`, whatever
+ * its kind. The server implements a member with its kind's `toLayer`, such as
+ * `Callable.toLayer(Users, "create", handler)`, and deploys the whole group
+ * with `Functions.group` from `@visiolab/effect-firebase-functions`. The
+ * client calls the group's Callables through `CallableClient.make(Users)`
+ * from `@visiolab/effect-firebase-client`.
+ *
+ * @example Declaring a group
+ * ```ts
+ * import { Schema } from "effect";
+ * import { Callable, FunctionGroup } from "@visiolab/effect-firebase/functions";
+ *
+ * const CreateUser = Callable.make("create", {
+ *   payload: { name: Schema.String },
+ *   success: Schema.String,
+ * });
+ * const DeleteUser = Callable.make("delete", { payload: { id: Schema.String } });
+ *
+ * class Users extends FunctionGroup.make("users").add(CreateUser, DeleteUser) {}
+ * ```
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+import type { Pipeable } from "effect";
+import type * as FirebaseFunction from "./FirebaseFunction.ts";
+import * as internal from "./internal/functionGroup.ts";
+
+const TypeId = internal.TypeId;
+
+/**
+ * A Function Group: a name and the Functions it deploys under that name.
+ *
+ * **Details**
+ *
+ * A group is a class, so `class Users extends FunctionGroup.make("users")`
+ * gives it a name of its own in types and in hovers. Its name is
+ * `identifier`, since a class already has a `name` of its own.
+ *
+ * A group holds Functions of any kind, so a group can follow a domain, such
+ * as `posts`, rather than a kind. A Function's name is unique within its
+ * group. `.add` checks this when the module loads; the types don't. A
+ * Function can be in more than one group, and each group serves and
+ * implements it separately. Groups don't nest.
+ *
+ * A group is only a name and its members. It carries no middleware: attach a
+ * Callable Middleware to each Callable that needs it with
+ * {@link Callable.Callable.middleware}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface FunctionGroup<
+  out Identifier extends string,
+  in out Functions extends FirebaseFunction.Any = never,
+>
+  extends Pipeable.Pipeable {
+  new (_: never): {};
+  readonly [TypeId]: typeof TypeId;
+  /** The group's name: the prefix its members deploy under. */
+  readonly identifier: Identifier;
+  /** The group's members, keyed by their names. */
+  readonly functions: { readonly [F in Functions as F["name"]]: F };
+
+  /**
+   * Adds Functions of any kind to the group.
+   *
+   * **Details**
+   *
+   * Returns a new group. Throws when a Function's name is already taken in
+   * the group, so a clash fails when the module loads, before anything
+   * deploys. The types don't catch a clash.
+   */
+  add<const A extends ReadonlyArray<FirebaseFunction.Any>>(
+    ...functions: A
+  ): FunctionGroup<Identifier, Functions | A[number]>;
+}
+
+/**
+ * Any {@link FunctionGroup}, whatever its name and members.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Any {
+  readonly [TypeId]: typeof TypeId;
+  readonly identifier: string;
+  readonly functions: { readonly [name: string]: FirebaseFunction.Any };
+}
+
+/**
+ * The members of a {@link FunctionGroup}, as a union of Functions.
+ *
+ * **When to use**
+ *
+ * Use to read every member of a group. Pass the `Any` of a kind as `K`, such
+ * as `Members<typeof Users, Callable.Any>`, to keep only the members of that
+ * kind.
+ *
+ * @see {@link Names} for the names of the members
+ * @see {@link Member} for the member of one name
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type Members<G, K extends FirebaseFunction.Any = FirebaseFunction.Any> = G extends {
+  readonly functions: infer Record;
+}
+  ? Extract<Record[keyof Record], K>
+  : never;
+
+/**
+ * The names of the members of a {@link FunctionGroup}.
+ *
+ * **When to use**
+ *
+ * Use to key something on a group's members. Pass the `Any` of a kind as `K`
+ * to keep only the names of the members of that kind.
+ *
+ * @see {@link Members} for the members themselves
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type Names<G, K extends FirebaseFunction.Any = FirebaseFunction.Any> = Members<G, K>["name"];
+
+/**
+ * The member of a {@link FunctionGroup} named `Name`.
+ *
+ * **When to use**
+ *
+ * Use to read one member's type by its name. Pass the `Any` of a kind as `K`
+ * to get `never` unless the member is of that kind.
+ *
+ * @see {@link Members} for every member
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type Member<
+  G,
+  Name extends string,
+  K extends FirebaseFunction.Any = FirebaseFunction.Any,
+> = Extract<Members<G, K>, { readonly name: Name }>;
+
+/**
+ * The {@link FirebaseFunction.Handler}s that serving a {@link FunctionGroup}
+ * needs: one per member, keyed by the group.
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type Handlers<G extends Any> =
+  Names<G> extends infer Name
+    ? Name extends string
+      ? FirebaseFunction.Handler<G["identifier"], Name>
+      : never
+    : never;
+
+/**
+ * Checks whether a value is a {@link FunctionGroup}. A building block for the
+ * functions and client packages, which take a Function or a group. Most apps
+ * don't need it.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.3.0
+ */
+export const isFunctionGroup: (u: unknown) => u is Any = internal.isFunctionGroup as never;
+
+/**
+ * Starts a Function Group with no members.
+ *
+ * **When to use**
+ *
+ * Use to collect related Functions, of any kind, under one prefix, and to
+ * deploy them as one. A Function that stands alone needs no group.
+ *
+ * **Details**
+ *
+ * Add members with `.add`. Extend the result as a class, so the group has a
+ * name of its own. Each member deploys as `<identifier>-<name>`.
+ *
+ * A client built from a Callable on its own, rather than from its group,
+ * calls the name without the prefix and fails with `not-found`. Nothing
+ * checks this at runtime.
+ *
+ * @example Serving one Callable in two groups
+ * ```ts
+ * import { Schema } from "effect";
+ * import { Callable, FunctionGroup } from "@visiolab/effect-firebase/functions";
+ *
+ * const GetUser = Callable.make("get", {
+ *   payload: { id: Schema.String },
+ *   success: Schema.String,
+ * });
+ *
+ * // Deploys as `users-get` and `admins-get`, each with a handler of its own.
+ * class Users extends FunctionGroup.make("users").add(GetUser) {}
+ * class Admins extends FunctionGroup.make("admins").add(GetUser) {}
+ * ```
+ *
+ * @see {@link Callable.make} for declaring a Callable member
+ * @see {@link Callable.toLayer} for implementing a Callable member
+ * @see {@link DocumentTrigger.created} for declaring a Document Trigger member
+ * @see {@link DocumentTrigger.toLayer} for implementing a Document Trigger member
+ * @see {@link Functions.group} for deploying the group
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.3.0
+ */
+export const make = <const Identifier extends string>(
+  identifier: Identifier,
+): FunctionGroup<Identifier> => internal.make({ identifier, functions: {} }) as never;

package/src/functions/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Callables: server functions declared once and shared by server and client.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+export * as Callable from "./Callable.ts";
+/**
+ * The error a Callable Client fails with when a call goes wrong in a way the
+ * contract doesn't declare.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+export * as CallableError from "./CallableError.ts";
+/**
+ * Callable Middleware: what runs around every call to the Callables it is
+ * attached to, before the Payload is decoded.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+export * as CallableMiddleware from "./CallableMiddleware.ts";
+/**
+ * The call a Callable is answering: who made it, from which app, and the raw
+ * Payload.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+export * as CallableRequest from "./CallableRequest.ts";
+/**
+ * Document Triggers: server functions that run when a document of a
+ * collection changes.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+export * as DocumentTrigger from "./DocumentTrigger.ts";
+/**
+ * Functions: what every kind of server function shares, whatever runs it.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+export * as FirebaseFunction from "./FirebaseFunction.ts";
+/**
+ * Function Groups: named sets of Functions of any kind that deploy under the
+ * group's name as a prefix.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+export * as FunctionGroup from "./FunctionGroup.ts";
+/**
+ * The Caller, the signed-in user making a call, and the built-in
+ * `Authenticated` middleware that provides it.
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+export * as Caller from "./Caller.ts";

package/src/functions/internal/callable.ts

@@ -0,0 +1,272 @@
+/** @internal */
+import { Context, Effect, Layer, Pipeable, Schema } from "effect";
+import * as HttpServerRequest from "effect/http/HttpServerRequest";
+import * as CallableError from "../CallableError.ts";
+import type * as CallableRequest from "../CallableRequest.ts";
+import type * as CallableMiddleware from "./callableMiddleware.ts";
+import * as callableRequest from "./callableRequest.ts";
+import * as FirebaseFunction from "./firebaseFunction.ts";
+
+/** @internal */
+export const TypeId = "~@visiolab/effect-firebase/functions/Callable";
+
+/** @internal */
+export const kind = "Callable";
+
+/** @internal */
+export interface Fields extends FirebaseFunction.Fields {
+  readonly kind: typeof kind;
+  readonly name: string;
+  readonly payload: Schema.Top;
+  readonly success: Schema.Top;
+  readonly error: ReadonlySet<Schema.Top>;
+  readonly middlewares: ReadonlySet<CallableMiddleware.Key>;
+}
+
+const Proto = {
+  [TypeId]: TypeId,
+  middleware(this: Fields, middleware: CallableMiddleware.Key) {
+    return make({
+      kind,
+      name: this.name,
+      payload: this.payload,
+      success: this.success,
+      error: this.error,
+      middlewares: new Set([...this.middlewares, middleware]),
+    });
+  },
+  pipe() {
+    return Pipeable.pipeArguments(this, arguments);
+  },
+};
+
+/** @internal */
+export const make = (fields: Fields): Fields => Object.assign(Object.create(Proto), fields);
+
+/**
+ * A handler as it sits in the context: the services it was built with are
+ * already provided, so it needs only those of the call.
+ *
+ * @internal
+ */
+export type HandlerService = (payload: unknown) => Effect.Effect<unknown, unknown>;
+
+/**
+ * What `toLayer` takes, with the types its signature has already checked
+ * erased.
+ *
+ * @internal
+ */
+export type HandlerInput = HandlerService | Effect.Effect<HandlerService>;
+
+/**
+ * The key of the handler of the Callable `name` in `group`, or in no group.
+ *
+ * @internal
+ */
+export const handlerKey = (group: string | undefined, name: string) =>
+  FirebaseFunction.handlerKey<HandlerService>(group, name);
+/** @internal */
+export const toLayer = (group: string | undefined, name: string, handler: HandlerInput) =>
+  Layer.effect(
+    handlerKey(group, name),
+    Effect.gen(function* () {
+      const run = Effect.isEffect(handler) ? yield* handler : handler;
+      // The services the Layer was built with, under those of the call.
+      const built = yield* Effect.context<never>();
+      return (payload: unknown) =>
+        Effect.updateContext(run(payload), (call: Context.Context<never>) =>
+          Context.merge(built, call),
+        );
+    }),
+  );
+
+/**
+ * Schemas with their services erased: a Callable's codecs need none that the
+ * types track, and `Schema.Top` leaves them `unknown`.
+ */
+const codec = (schema: Schema.Top) => Schema.toCodecJson(schema as Schema.Codec<unknown>);
+
+/** @internal */
+export const getErrorCode = (schema: Schema.Top): CallableError.ErrorCode =>
+  Schema.resolveAnnotations(schema)?.callableErrorCode ?? "internal";
+
+/**
+ * The name `callable` is deployed under: its own in no group, or
+ * `<group>-<name>` in `group`. The server exports it under this name, and the
+ * client calls it.
+ *
+ * @internal
+ */
+export const deployedName: (group: FirebaseFunction.Group | undefined, callable: Fields) => string =
+  FirebaseFunction.deployedName;
+
+/**
+ * The attributes of the server's and the client's span of a call to
+ * `callable` in `group`, or in no group.
+ *
+ * @internal
+ */
+export const spanAttributes = (
+  group: FirebaseFunction.Group | undefined,
+  callable: Fields,
+): Readonly<Record<string, string>> => ({
+  "rpc.system": "firebase_callable",
+  "rpc.method": callable.name,
+  ...(group === undefined ? {} : { "rpc.service": group.identifier }),
+  "faas.name": deployedName(group, callable),
+});
+
+/**
+ * The schemas of every error a call to `callable` can be answered with: its
+ * declared errors, then those of its middleware.
+ *
+ * @internal
+ */
+export const errorSchemas = (callable: Fields): ReadonlyArray<Schema.Top> => [
+  ...callable.error,
+  ...[...callable.middlewares].flatMap((middleware) => [...middleware.error]),
+];
+
+/**
+ * Turns a failure of the call into the answer that carries it: the code of
+ * the error schema it matches, a readable message, and the encoded error. A
+ * failure no schema matches, or one that doesn't encode, is a defect.
+ */
+const encodeFailure = (schemas: ReadonlyArray<Schema.Top>, error: unknown) =>
+  Effect.gen(function* () {
+    for (const schema of schemas) {
+      if (!Schema.is(schema as Schema.Codec<unknown>)(error)) continue;
+      const code = getErrorCode(schema);
+      const details = yield* Effect.orDie(Schema.encodeUnknownEffect(codec(schema))(error));
+      const fields = error as { readonly message?: unknown; readonly _tag?: unknown };
+      const message =
+        typeof fields.message === "string" && fields.message !== ""
+          ? fields.message
+          : typeof fields._tag === "string"
+            ? fields._tag
+            : code;
+      return new CallableError.ResponseError({ code, message, details });
+    }
+    return yield* Effect.die(error);
+  });
+
+/**
+ * The failure of a raw Payload that doesn't decode, as it leaves the chain.
+ * Middleware sees it like any other failure.
+ */
+class PayloadDecodeError {
+  constructor(readonly cause: Schema.SchemaError) {}
+}
+
+/**
+ * The middleware chain of `callable` in `group`, or in no group, around the
+ * Payload's decoding and the handler. `serve`, which `Functions` runs,
+ * and `handler` both run this one chain.
+ *
+ * The middleware implementations are read from the context once. The context
+ * the chain was read in sits under that of each call, and the call's request
+ * on top of both.
+ *
+ * @internal
+ */
+export const chain = (group: FirebaseFunction.Group | undefined, callable: Fields) =>
+  Effect.gen(function* () {
+    const handler = yield* Effect.service(handlerKey(group?.identifier, callable.name));
+    const context = yield* Effect.context<never>();
+    // Innermost first: a middleware attached later wraps the ones before it.
+    const implementations = [...callable.middlewares].map((key) => Context.getUnsafe(context, key));
+    const decode = Schema.decodeUnknownEffect(codec(callable.payload));
+    return (request: CallableRequest.CallableRequest): Effect.Effect<unknown, unknown> => {
+      let effect: Effect.Effect<unknown, unknown> = decode(request.data).pipe(
+        Effect.mapError((cause) => new PayloadDecodeError(cause)),
+        Effect.flatMap(handler),
+      );
+      for (const implementation of implementations) {
+        effect = implementation(effect, { callable });
+      }
+      return effect.pipe(
+        Effect.provideService(callableRequest.CallableRequest, request),
+        Effect.updateContext((call: Context.Context<never>) => Context.merge(context, call)),
+      );
+    };
+  });
+
+/** @internal */
+export const serve = (group: FirebaseFunction.Group | undefined, callable: Fields) =>
+  Effect.map(chain(group, callable), (run) => {
+    const encode = Schema.encodeUnknownEffect(codec(callable.success));
+    const schemas = errorSchemas(callable);
+    const fail = (reason: CallableError.ResponseError) =>
+      new CallableError.CallableError({
+        callable: deployedName(group, callable),
+        reason,
+      });
+    return (request: CallableRequest.CallableRequest) =>
+      run(request).pipe(
+        Effect.catch((error) =>
+          error instanceof PayloadDecodeError
+            ? Effect.logDebug("The Payload of a Callable didn't decode", error.cause).pipe(
+                Effect.andThen(
+                  Effect.fail(
+                    fail(
+                      new CallableError.ResponseError({
+                        code: "invalid-argument",
+                        message: "The Payload didn't decode",
+                        details: undefined,
+                      }),
+                    ),
+                  ),
+                ),
+              )
+            : Effect.flatMap(encodeFailure(schemas, error), (reason) => Effect.fail(fail(reason))),
+        ),
+        Effect.flatMap((value) => Effect.orDie(encode(value))),
+      );
+  });
+
+/**
+ * The HTTP request of a call `handler` runs with no request given: a JSON
+ * `POST` of the encoded Payload to the deployed name.
+ */
+const syntheticRequest = (name: string, data: unknown) =>
+  HttpServerRequest.fromWeb(
+    new Request(`http://localhost/${name}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(data),
+    }),
+  );
+
+/** @internal */
+export const handler = (group: FirebaseFunction.Group | undefined, callable: Fields) =>
+  Effect.map(chain(group, callable), (run) => {
+    const encode = Schema.encodeUnknownEffect(codec(callable.payload));
+    const name = deployedName(group, callable);
+    return (payload: unknown, input: CallableRequest.Input) =>
+      encode(payload).pipe(
+        Effect.orDie,
+        Effect.flatMap((data) =>
+          run({
+            auth:
+              input.auth === undefined
+                ? undefined
+                : {
+                    uid: input.auth.uid,
+                    token: input.auth.token,
+                    rawToken: input.auth.rawToken ?? "",
+                  },
+            app: input.app,
+            instanceIdToken: input.instanceIdToken,
+            data,
+            rawRequest: input.rawRequest ?? syntheticRequest(name, data),
+          }),
+        ),
+        // The Payload was encoded from its own type, so a Payload that doesn't
+        // decode back is a defect of its schema.
+        Effect.catchIf(
+          (error): error is PayloadDecodeError => error instanceof PayloadDecodeError,
+          (error) => Effect.die(error.cause),
+        ),
+      );
+  });