@visiolab/effect-firebase 0.0.0-stage → 0.3.1

package/src/functions/CallableError.ts

@@ -0,0 +1,348 @@
+/**
+ * Errors of Callables: Firebase's error codes, built-in errors that carry
+ * them, and 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
+ */
+import { Schema } from "effect";
+
+/**
+ * Firebase's error codes, as `firebase-functions` and the client SDK name
+ * them, without `ok`.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 0.3.0
+ */
+export const ErrorCode = Schema.Literals([
+  "cancelled",
+  "unknown",
+  "invalid-argument",
+  "deadline-exceeded",
+  "not-found",
+  "already-exists",
+  "permission-denied",
+  "resource-exhausted",
+  "failed-precondition",
+  "aborted",
+  "out-of-range",
+  "unimplemented",
+  "internal",
+  "unavailable",
+  "data-loss",
+  "unauthenticated",
+]);
+
+/**
+ * One of Firebase's error codes, such as `not-found`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export type ErrorCode = typeof ErrorCode.Type;
+
+declare module "effect/Schema" {
+  namespace Annotations {
+    interface Annotations {
+      /**
+       * The Firebase error code a Callable answers with when it fails with
+       * this error. Set it with `Callable.errorCode` or in a `TaggedError`'s
+       * annotations, and read it with `Callable.getErrorCode`.
+       */
+      readonly callableErrorCode?: ErrorCode | undefined;
+    }
+  }
+}
+
+/**
+ * The resource the call asks for doesn't exist. Its code is `not-found`.
+ *
+ * @example Failing with a built-in error
+ * ```ts
+ * import { Effect, Schema } from "effect";
+ * import { Callable, CallableError } from "@visiolab/effect-firebase/functions";
+ *
+ * const GetUser = Callable.make("getUser", {
+ *   payload: { id: Schema.String },
+ *   success: Schema.String,
+ *   error: CallableError.NotFound,
+ * });
+ *
+ * const GetUserLive = Callable.toLayer(GetUser, ({ id }) =>
+ *   Effect.fail(new CallableError.NotFound({ message: `No user ${id}` })),
+ * );
+ * ```
+ *
+ * @stability unstable
+ * @category built-in errors
+ * @since 0.3.0
+ */
+export class NotFound extends Schema.TaggedError<NotFound, { readonly brand: unique symbol }>()(
+  "NotFound",
+  { message: Schema.optional(Schema.String) },
+  { callableErrorCode: "not-found" },
+) {}
+
+/**
+ * The caller may not do what the call asks. Its code is `permission-denied`.
+ *
+ * @see {@link Unauthenticated} for a caller who isn't signed in
+ *
+ * @stability unstable
+ * @category built-in errors
+ * @since 0.3.0
+ */
+export class PermissionDenied extends Schema.TaggedError<
+  PermissionDenied,
+  { readonly brand: unique symbol }
+>()(
+  "PermissionDenied",
+  { message: Schema.optional(Schema.String) },
+  { callableErrorCode: "permission-denied" },
+) {}
+
+/**
+ * The caller isn't signed in. Its code is `unauthenticated`.
+ *
+ * @see {@link PermissionDenied} for a signed-in caller who may not do this
+ *
+ * @stability unstable
+ * @category built-in errors
+ * @since 0.3.0
+ */
+export class Unauthenticated extends Schema.TaggedError<
+  Unauthenticated,
+  { readonly brand: unique symbol }
+>()(
+  "Unauthenticated",
+  { message: Schema.optional(Schema.String) },
+  { callableErrorCode: "unauthenticated" },
+) {}
+
+/**
+ * The Payload is well-formed but its values are wrong. Its code is
+ * `invalid-argument`.
+ *
+ * **Details**
+ *
+ * A Payload that doesn't decode is answered with `invalid-argument` already,
+ * without this error. Use it for checks the Payload's schema can't express.
+ *
+ * @see {@link FailedPrecondition} for a valid Payload the current state rejects
+ *
+ * @stability unstable
+ * @category built-in errors
+ * @since 0.3.0
+ */
+export class InvalidArgument extends Schema.TaggedError<
+  InvalidArgument,
+  { readonly brand: unique symbol }
+>()(
+  "InvalidArgument",
+  { message: Schema.optional(Schema.String) },
+  { callableErrorCode: "invalid-argument" },
+) {}
+
+/**
+ * What the call would create exists already. Its code is `already-exists`.
+ *
+ * @stability unstable
+ * @category built-in errors
+ * @since 0.3.0
+ */
+export class AlreadyExists extends Schema.TaggedError<
+  AlreadyExists,
+  { readonly brand: unique symbol }
+>()(
+  "AlreadyExists",
+  { message: Schema.optional(Schema.String) },
+  { callableErrorCode: "already-exists" },
+) {}
+
+/**
+ * The system isn't in the state the call needs. Its code is
+ * `failed-precondition`.
+ *
+ * @see {@link InvalidArgument} for a Payload that is wrong whatever the state
+ *
+ * @stability unstable
+ * @category built-in errors
+ * @since 0.3.0
+ */
+export class FailedPrecondition extends Schema.TaggedError<
+  FailedPrecondition,
+  { readonly brand: unique symbol }
+>()(
+  "FailedPrecondition",
+  { message: Schema.optional(Schema.String) },
+  { callableErrorCode: "failed-precondition" },
+) {}
+
+/**
+ * A quota or rate limit ran out. Its code is `resource-exhausted`.
+ *
+ * @stability unstable
+ * @category built-in errors
+ * @since 0.3.0
+ */
+export class ResourceExhausted extends Schema.TaggedError<
+  ResourceExhausted,
+  { readonly brand: unique symbol }
+>()(
+  "ResourceExhausted",
+  { message: Schema.optional(Schema.String) },
+  { callableErrorCode: "resource-exhausted" },
+) {}
+
+/**
+ * The service can't answer right now, and the call may succeed if retried.
+ * Its code is `unavailable`.
+ *
+ * @stability unstable
+ * @category built-in errors
+ * @since 0.3.0
+ */
+export class Unavailable extends Schema.TaggedError<
+  Unavailable,
+  { readonly brand: unique symbol }
+>()(
+  "Unavailable",
+  { message: Schema.optional(Schema.String) },
+  { callableErrorCode: "unavailable" },
+) {}
+
+/**
+ * No response arrived: the request never reached the server, the connection
+ * broke before it answered, or the client gave up waiting.
+ *
+ * **Details**
+ *
+ * The client SDK appends the HTTP status of an answer to its error's message
+ * as ` [<status>]`, and reports a network failure as status 0. The errors the
+ * SDK makes itself carry no status: its timeout (`deadline-exceeded`), a
+ * cancelled call, and a deleted Functions instance. `CallableClient` treats
+ * an error without a status, or with status 0, as a `TransportError`, except
+ * for an answer the SDK can't read, which is a {@link DecodeError}.
+ *
+ * @see {@link ResponseError} for an error the server answered with
+ *
+ * @stability unstable
+ * @category errors
+ * @since 0.3.0
+ */
+export class TransportError extends Schema.TaggedError<
+  TransportError,
+  { readonly brand: unique symbol }
+>()("TransportError", {
+  /** What the SDK threw. */
+  cause: Schema.Defect(),
+}) {}
+
+/**
+ * The server answered with an error the contract doesn't declare.
+ *
+ * **Details**
+ *
+ * `code` is Firebase's error code without its `functions/` prefix, such as
+ * `not-found`. `not-found` usually means the client calls the wrong region or
+ * a name the server doesn't export.
+ *
+ * Only an error the server answered with, with a non-zero HTTP status, is a
+ * `ResponseError`. A `deadline-exceeded` the server sends is one; the client
+ * SDK's own timeout, which has the same code, is a {@link TransportError}.
+ *
+ * @see {@link TransportError} for a call no answer arrived for
+ *
+ * @stability unstable
+ * @category errors
+ * @since 0.3.0
+ */
+export class ResponseError extends Schema.TaggedError<
+  ResponseError,
+  { readonly brand: unique symbol }
+>()("ResponseError", {
+  /** Firebase's error code, such as `internal`. */
+  code: ErrorCode,
+  /** The error's message, without the SDK's ` [status]` suffix. */
+  message: Schema.String,
+  /** The error's `details`, as the server sent them. */
+  details: Schema.Unknown,
+}) {}
+
+/**
+ * The Payload didn't encode through its `Schema.toCodecJson`, so nothing was
+ * sent.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 0.3.0
+ */
+export class EncodeError extends Schema.TaggedError<
+  EncodeError,
+  { readonly brand: unique symbol }
+>()("EncodeError", {
+  /** The `Schema.SchemaError` of the encode. */
+  cause: Schema.Defect(),
+}) {}
+
+/**
+ * The server's answer didn't decode against the contract, as after the server
+ * and the client drift apart.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 0.3.0
+ */
+export class DecodeError extends Schema.TaggedError<
+  DecodeError,
+  { readonly brand: unique symbol }
+>()("DecodeError", {
+  /** The `Schema.SchemaError` of the decode. */
+  cause: Schema.Defect(),
+}) {}
+
+/**
+ * What went wrong with a call, as one of the reasons above.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export type Reason = TransportError | ResponseError | EncodeError | DecodeError;
+
+/**
+ * A call to a Callable failed in a way the contract doesn't declare.
+ *
+ * **When to use**
+ *
+ * Use `Effect.catchReason` on its `reason` to recover from one kind of
+ * failure, such as a missing response.
+ *
+ * @example Recovering from a missing response
+ * ```ts
+ * import { Effect } from "effect";
+ * import type { CallableError } from "@visiolab/effect-firebase/functions";
+ *
+ * declare const call: Effect.Effect<string, CallableError.CallableError>;
+ *
+ * const program = call.pipe(
+ *   Effect.catchReason("CallableError", "TransportError", () => Effect.succeed("offline")),
+ * );
+ * ```
+ *
+ * @stability unstable
+ * @category errors
+ * @since 0.3.0
+ */
+export class CallableError extends Schema.TaggedError<
+  CallableError,
+  { readonly brand: unique symbol }
+>()("CallableError", {
+  /** The deployed name of the Callable Function that was called. */
+  callable: Schema.String,
+  /** What went wrong. */
+  reason: Schema.Union([TransportError, ResponseError, EncodeError, DecodeError]),
+}) {}

package/src/functions/CallableMiddleware.ts

@@ -0,0 +1,279 @@
+/**
+ * Callable Middleware: what runs around every call to the Callables it is
+ * attached to, before the Payload is decoded.
+ *
+ * A middleware is declared once, with what it provides to the handler, what it
+ * requires from middleware outside it and the errors it can fail with. It is
+ * attached to a Callable with `.middleware(M)`, and implemented as a Layer of a
+ * function that wraps the call. The implementation is provided where the
+ * chain runs: to `Functions` from `@visiolab/effect-firebase-functions`,
+ * or to `Callable.handler`.
+ *
+ * @example Declaring, attaching and implementing a middleware
+ * ```ts
+ * import { Context, Effect, Layer, Schema } from "effect";
+ * import { Callable, CallableError, CallableMiddleware, CallableRequest } from "@visiolab/effect-firebase/functions";
+ *
+ * class Tenant extends Context.Service<Tenant, { readonly id: string }>()("Tenant") {}
+ *
+ * class WithTenant extends CallableMiddleware.Service<WithTenant, { provides: Tenant }>()(
+ *   "WithTenant",
+ *   { error: CallableError.PermissionDenied },
+ * ) {}
+ *
+ * const ListUsers = Callable.make("listUsers", { success: Schema.Array(Schema.String) }).middleware(
+ *   WithTenant,
+ * );
+ *
+ * const WithTenantLive = Layer.succeed(WithTenant, (effect) =>
+ *   Effect.gen(function* () {
+ *     const { auth } = yield* CallableRequest.CallableRequest;
+ *     const id = auth?.token["tenant"];
+ *     if (typeof id !== "string") return yield* new CallableError.PermissionDenied();
+ *     return yield* Effect.provideService(effect, Tenant, { id });
+ *   }),
+ * );
+ * ```
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+import type { Context, Effect, Schema } from "effect";
+import type { unhandled } from "effect/Types";
+import type * as Callable from "./Callable.ts";
+// Only the documentation links to it.
+// oxlint-disable-next-line no-unused-vars
+import type * as CallableRequest from "./CallableRequest.ts";
+import * as internal from "./internal/callableMiddleware.ts";
+
+const TypeId = internal.TypeId;
+
+/**
+ * The errors a middleware can fail with: one schema or an array.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export type ErrorConstraint = Schema.Top | ReadonlyArray<Schema.Top>;
+
+type ErrorSchemaFromConstraint<E> =
+  E extends ReadonlyArray<Schema.Top> ? E[number] : E extends Schema.Top ? E : never;
+
+/**
+ * What a middleware's implementation is told about the call it wraps.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Options {
+  /** The Callable being called. */
+  readonly callable: Callable.Any;
+}
+
+/**
+ * The implementation of a middleware: a function that wraps the rest of the
+ * call.
+ *
+ * **Details**
+ *
+ * `effect` is the rest of the call: the middleware inside this one, the
+ * Payload's decoding and the handler. It needs what this middleware
+ * `Provides`. The implementation may run it, fail instead, or catch what it
+ * fails with. It may require what middleware outside it provides, and always
+ * the {@link CallableRequest.CallableRequest}.
+ *
+ * A Payload that doesn't decode fails `effect` too. An implementation that
+ * catches every failure catches that one as well, and the caller then no
+ * longer gets `invalid-argument`. Catch only the errors you mean to.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export type CallableMiddleware<Provides, E extends ErrorConstraint, Requires> = (
+  effect: Effect.Effect<unknown, unhandled, Provides>,
+  options: Options,
+) => Effect.Effect<
+  unknown,
+  unhandled | ErrorSchemaFromConstraint<E>["Type"],
+  Requires | CallableRequest.CallableRequest
+>;
+
+/**
+ * Any middleware, as the type of its service class's instances: what it
+ * provides, requires and fails with.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface AnyId {
+  readonly [TypeId]: {
+    readonly provides: any;
+    readonly requires: any;
+    readonly error: ErrorConstraint;
+  };
+}
+
+/**
+ * Any middleware's service key, as `.middleware` takes it.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface AnyKey extends Context.Key<any, any> {
+  readonly [TypeId]: typeof TypeId;
+  /** The schemas of the errors the middleware can fail with. */
+  readonly error: ReadonlySet<Schema.Top>;
+}
+
+/**
+ * The services a middleware provides to what it wraps.
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: infer P } }
+  ? P
+  : never;
+
+/**
+ * The services a middleware requires from the middleware outside it.
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: infer R } }
+  ? R
+  : never;
+
+/**
+ * The services still required after wrapping `R` in the middleware `A`: `A`'s
+ * `provides` are removed and its `requires` added.
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type ApplyServices<A extends AnyId, R> = Exclude<R, Provides<A>> | Requires<A>;
+
+/**
+ * The union of the error schemas of a middleware.
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: infer E } }
+  ? ErrorSchemaFromConstraint<E>
+  : never;
+
+/**
+ * The errors a middleware can fail with.
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type Error<A> = ErrorSchema<A>["Type"];
+
+/**
+ * The class {@link Service} returns: a service key whose instances carry the
+ * middleware's types.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export type ServiceClass<
+  Self,
+  Id extends string,
+  Config extends { requires: any; provides: any; error: ErrorConstraint },
+> = Context.Service<
+  Self,
+  CallableMiddleware<Config["provides"], Config["error"], Config["requires"]>
+> & {
+  new (_: never): Context.ServiceClass.Shape<
+    Id,
+    CallableMiddleware<Config["provides"], Config["error"], Config["requires"]>
+  > & {
+    readonly [TypeId]: {
+      readonly error: Config["error"];
+      readonly requires: Config["requires"];
+      readonly provides: Config["provides"];
+    };
+  };
+  readonly [TypeId]: typeof TypeId;
+  /** The schemas of the errors the middleware can fail with. */
+  readonly error: ReadonlySet<Schema.Top>;
+};
+
+/**
+ * Declares a Callable Middleware as a class.
+ *
+ * **When to use**
+ *
+ * Use to state a requirement of a Callable, such as "the caller is a member of
+ * a tenant", as part of its contract. For "the caller is signed in", use the
+ * built-in `Caller.Authenticated`.
+ *
+ * **Details**
+ *
+ * `provides` is what the middleware gives the handler: the handler's Layer no
+ * longer needs it. `requires` is what it needs from middleware outside it; a
+ * `requires` that nothing outside provides is left for the Layers where the
+ * chain runs. The {@link CallableRequest.CallableRequest} is always there and
+ * is never listed.
+ *
+ * `error` is one schema or an array. A middleware's errors join the error
+ * union of every Callable it is attached to. They are sent like the
+ * Callable's declared errors, and the client decodes them back.
+ *
+ * The middleware runs before the Payload is decoded, so a call it rejects
+ * learns nothing from the Payload's decoding. The decoding runs inside the
+ * chain, so an implementation that catches every failure also catches a
+ * Payload that doesn't decode.
+ *
+ * @example Declaring a middleware
+ * ```ts
+ * import { Context } from "effect";
+ * import { CallableError, CallableMiddleware } from "@visiolab/effect-firebase/functions";
+ *
+ * class Tenant extends Context.Service<Tenant, { readonly id: string }>()("Tenant") {}
+ *
+ * class WithTenant extends CallableMiddleware.Service<WithTenant, { provides: Tenant }>()(
+ *   "WithTenant",
+ *   { error: CallableError.PermissionDenied },
+ * ) {}
+ * ```
+ *
+ * @see {@link Callable.Callable.middleware} for attaching it to a Callable
+ * @see {@link Caller.Authenticated} for the built-in middleware
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.3.0
+ */
+export const Service =
+  <
+    Self,
+    Config extends { requires?: any; provides?: any } = { requires: never; provides: never },
+  >() =>
+  <const Id extends string, const Error extends ErrorConstraint = never>(
+    id: Id,
+    options?: { readonly error?: Error | undefined },
+  ): ServiceClass<
+    Self,
+    Id,
+    {
+      requires: "requires" extends keyof Config ? Config["requires"] : never;
+      provides: "provides" extends keyof Config ? Config["provides"] : never;
+      error: Error;
+    }
+  > =>
+    internal.Service(id, options);