Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

14.1 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import type { Database } from "@carbon/database";
import type { Kysely, KyselyDatabase } from "@carbon/database/client";
import type { redis } from "@carbon/kv";
import { getLogger } from "@carbon/logger";
import type { SupabaseClient } from "@supabase/supabase-js";
import { z } from "zod";
import { databaseRefusal } from "./database-refusal";
import {
  hasPermissions,
  type ModulePermissions,
  type PermissionRule,
  type Permissions,
  resolvePermissions
} from "./permissions";

const logger = getLogger("api", "service-fn");

/** Every way a service function refuses, and the HTTP status it maps to. */
export const ERROR_STATUS = {
  validation: 400,
  unauthenticated: 401,
  entitlement: 402,
  forbidden: 403,
  notFound: 404,
  conflict: 409,
  rule: 422,
  rateLimited: 429,
  internal: 500,
  unavailable: 503
} as const;

export type ErrorCategory = keyof typeof ERROR_STATUS;

/**
 * The one error a service function returns. `message` is written for the
 * user; `cause` is the underlying failure and is logged, never shown.
 */
export class CarbonError<
  C extends ErrorCategory = ErrorCategory
> extends Error {
  readonly category: C;
  readonly cause?: unknown;

  constructor(category: C, message: string, cause?: unknown) {
    // A refusal is an expected outcome that is returned, not thrown: nobody
    // reads its stack, and capturing one is most of what creating it costs.
    const limit = Error.stackTraceLimit;
    if (category !== "internal") Error.stackTraceLimit = 0;
    super(message);
    Error.stackTraceLimit = limit;
    this.category = category;
    this.cause = cause;
  }

  get status(): (typeof ERROR_STATUS)[C] {
    return ERROR_STATUS[this.category];
  }
}
CarbonError.prototype.name = "CarbonError";

export type Result<T, E extends CarbonError = CarbonError> =
  | { data: T; error: null }
  | { data: null; error: E };

/**
 * Who made the call, and what they hold. Stated by the entry point that
 * authenticated it; the gate checks every entry call against it.
 */
export type Actor =
  | { type: "user"; userId: string; permissions: ModulePermissions }
  | { type: "apiKey"; createdBy: string; scopes: ModulePermissions }
  | { type: "system"; onBehalfOf: string };

type Kv = typeof redis;

export type ServiceContext = {
  actor: Actor;
  company: { id: string; groupId: string };
  /**
   * Runs as the caller: row-level security applies. Not part of a
   * transaction: inside `ctx.transaction` reading it throws.
   */
  asCaller: { supabase: SupabaseClient<Database> };
  /** Bypasses row-level security: every query scopes by `company.id` itself. */
  asSystem: {
    supabase: SupabaseClient<Database>;
    pg: Kysely<KyselyDatabase>;
  };
  kv: Kv;
  /** The user id audit columns record: the user, a key's creator, or the user a job acts for. */
  auditUserId: string;
  /**
   * Whether the actor also holds `required`: for a permission that depends on
   * the data, which the entry gate cannot know. The system actor holds all.
   */
  can(required: Permissions): boolean;
  error<C extends ErrorCategory>(
    category: C,
    message: string,
    cause?: unknown
  ): CarbonError<C>;
  /**
   * Runs `fn` in one transaction on `asSystem.pg`. A returned refusal (a
   * `CarbonError`, or a service function's `{ data, error }` with one) rolls
   * back, as a throw does, and is returned as the error. Called inside a
   * transaction, it joins it: the refusal is returned and the outer
   * transaction rolls back when its own body returns it.
   */
  transaction<R>(fn: (tx: ServiceContext) => Promise<R>): Promise<Settled<R>>;
};

/** The refusal a transaction's body can return: bare, or a service function's error. */
type Refusal<R> =
  | Extract<R, CarbonError>
  | (R extends { data: unknown; error: infer E }
      ? Extract<E, CarbonError>
      : never);

/** A transaction's result: the body's value, or the refusal that rolled it back. */
export type Settled<R> = Result<
  Exclude<R, CarbonError | { data: unknown; error: CarbonError }>,
  Refusal<R>
>;

type Handles = {
  actor: Actor;
  company: { id: string; groupId: string };
  caller: SupabaseClient<Database>;
  system: () => SupabaseClient<Database>;
  pg: () => Kysely<KyselyDatabase>;
  kv: () => Kv;
};

class Rollback {
  readonly error: CarbonError;
  constructor(error: CarbonError) {
    this.error = error;
  }
}

function auditUserIdOf(actor: Actor): string {
  if (actor.type === "user") return actor.userId;
  if (actor.type === "apiKey") return actor.createdBy;
  return actor.onBehalfOf;
}

function refusalIn(out: unknown): CarbonError | null {
  if (out instanceof CarbonError) return out;
  if (out !== null && typeof out === "object" && "data" in out) {
    const { error } = out as { error?: unknown };
    if (error instanceof CarbonError) return error;
  }
  return null;
}

function settle<R>(out: R): Settled<R> {
  const error = refusalIn(out);
  return (
    error ? { data: null, error } : { data: out, error: null }
  ) as Settled<R>;
}

// Classes, not object literals with getters: a context is built for every
// request, and this way it costs a few field writes, with the accessors and
// methods shared on the prototype instead of allocated per context.
class CallerHandles {
  private readonly client: SupabaseClient<Database>;
  private readonly inTransaction: boolean;

  constructor(client: SupabaseClient<Database>, inTransaction: boolean) {
    this.client = client;
    this.inTransaction = inTransaction;
  }

  get supabase() {
    if (this.inTransaction) {
      throw new Error(
        "The caller's client is not part of the transaction: use asSystem.pg"
      );
    }
    return this.client;
  }
}

class SystemHandles {
  private readonly handles: Handles;

  constructor(handles: Handles) {
    this.handles = handles;
  }

  get supabase() {
    return this.handles.system();
  }

  get pg() {
    return this.handles.pg();
  }
}

class Context implements ServiceContext {
  readonly actor: Actor;
  readonly company: { id: string; groupId: string };
  readonly asCaller: CallerHandles;
  readonly asSystem: SystemHandles;
  readonly auditUserId: string;
  /**
   * Set on the context a service function's `run` receives. A call made from
   * inside a service function was authorized by that function's gate (a
   * system-only function is still checked).
   */
  readonly nested: boolean;
  private readonly handles: Handles;
  private readonly inTransaction: boolean;

  constructor(handles: Handles, nested: boolean, inTransaction: boolean) {
    this.actor = handles.actor;
    this.company = handles.company;
    this.asCaller = new CallerHandles(handles.caller, inTransaction);
    this.asSystem = new SystemHandles(handles);
    this.auditUserId = auditUserIdOf(handles.actor);
    this.nested = nested;
    this.handles = handles;
    this.inTransaction = inTransaction;
  }

  get kv() {
    return this.handles.kv();
  }

  can(required: Permissions): boolean {
    return allows(this.actor, this.company.id, required);
  }

  inside(): Context {
    return this.nested
      ? this
      : new Context(this.handles, true, this.inTransaction);
  }

  error<C extends ErrorCategory>(
    category: C,
    message: string,
    cause?: unknown
  ): CarbonError<C> {
    return new CarbonError(category, message, cause);
  }

  async transaction<R>(
    fn: (tx: ServiceContext) => Promise<R>
  ): Promise<Settled<R>> {
    const pg = this.handles.pg();
    if (pg.isTransaction) {
      return settle(
        await fn(
          this.inTransaction
            ? this
            : new Context(this.handles, this.nested, true)
        )
      );
    }

    try {
      return settle(
        await pg.transaction().execute(async (trx) => {
          const tx = new Context(
            { ...this.handles, pg: () => trx },
            this.nested,
            true
          );
          const out = await fn(tx);
          const refusal = refusalIn(out);
          if (refusal) throw new Rollback(refusal);
          return out;
        })
      );
    } catch (err) {
      if (err instanceof Rollback) {
        return { data: null, error: err.error } as Settled<R>;
      }
      throw err;
    }
  }
}

export function createServiceContext(handles: Handles): ServiceContext {
  return new Context(handles, false, false);
}

function allows(
  actor: Actor,
  companyId: string,
  required: Permissions
): boolean {
  if (actor.type === "system") return true;
  if (required === "system") return false;
  return hasPermissions(
    actor.type === "user" ? actor.permissions : actor.scopes,
    companyId,
    required
  );
}

/** What a failure log says of the input: its keys. Values can be files, notes, emails. */
function keysOf(input: unknown): string[] | string {
  return input !== null && typeof input === "object"
    ? Object.keys(input)
    : typeof input;
}

function failed<R>(error: CarbonError) {
  return { data: null, error } as Outcome<R>;
}

type Outcome<R> = Result<
  Exclude<R, CarbonError>,
  Extract<R, CarbonError> | CarbonError<"internal" | "validation" | "forbidden">
>;

export type ServiceFn<I extends z.ZodType, R> = {
  (ctx: ServiceContext, input: z.input<I>): Promise<Outcome<R>>;
  input: I;
  permission: PermissionRule<z.output<I>>;
};

/**
 * Define an operation once: its input, who may run it, and what it does.
 *
 * `run` returns its value, or `ctx.error(...)` to refuse. Callers always get
 * `{ data, error }` and never an exception: anything `run` throws comes back
 * as an `internal` error with the detail logged and withheld.
 *
 * Every entry call is checked against `permission` for its actor. A call made
 * from inside another service function's `run` is not checked again, except
 * that a system-only function still admits only the system actor.
 */
export function defineServiceFn<I extends z.ZodType, R>(definition: {
  input: I;
  permission: PermissionRule<z.output<I>>;
  run(ctx: ServiceContext, input: z.output<I>): Promise<R>;
}): ServiceFn<I, R> {
  // Compiled on the first call, not at import: a module of service functions
  // would otherwise pay for every schema at startup, used or not.
  let schema: I | undefined;

  const call = async (
    ctx: ServiceContext,
    input: z.input<I>
  ): Promise<Outcome<R>> => {
    schema ??= z.compile(definition.input);
    const parsed = schema.safeParse(input);
    if (!parsed.success) {
      return failed(
        new CarbonError("validation", z.prettifyError(parsed.error))
      );
    }

    let required: Permissions;
    try {
      required = resolvePermissions(definition.permission, parsed.data);
    } catch (err) {
      // A keyed rule with no entry for the value: bad input, not a 403.
      return failed(
        new CarbonError(
          "validation",
          err instanceof Error ? err.message : "Invalid input"
        )
      );
    }
    // A nested call was authorized by the outer function's gate, but no gate
    // admits anyone but the system to a system-only function.
    const admitted =
      ctx instanceof Context && ctx.nested
        ? required !== "system" || ctx.actor.type === "system"
        : allows(ctx.actor, ctx.company.id, required);
    if (!admitted) {
      logger.warn("Service function refused: {actor}", {
        actor: ctx.actor.type,
        companyId: ctx.company.id,
        required
      });
      return failed(
        new CarbonError("forbidden", "You do not have permission to do this")
      );
    }

    try {
      const out = await definition.run(
        ctx instanceof Context ? ctx.inside() : ctx,
        parsed.data
      );
      if (!(out instanceof CarbonError)) {
        return { data: out, error: null } as Outcome<R>;
      }
      if (out.category === "internal") {
        const refused = refusalFromDatabase(out.message, out.cause);
        logger[refused ? "warn" : "error"](
          "Service function failed: {message}: {error}",
          {
            message: out.message,
            companyId: ctx.company.id,
            inputKeys: keysOf(input),
            error: out.cause
          }
        );
        if (refused) return failed(refused);
      }
      return failed(out);
    } catch (err) {
      const refused = refusalFromDatabase(undefined, err);
      logger[refused ? "warn" : "error"]("Service function threw: {error}", {
        companyId: ctx.company.id,
        inputKeys: keysOf(input),
        error: err
      });
      return failed(
        refused ?? new CarbonError("internal", "Something went wrong", err)
      );
    }
  };

  return Object.assign(call, {
    input: definition.input,
    permission: definition.permission
  });
}

/**
 * An `internal` failure whose cause is a database refusal the caller can fix
 * (a duplicate id, a reference to nothing, a missing value) is that refusal:
 * its category, and a message that names the field after the operation's own.
 */
function refusalFromDatabase(
  message: string | undefined,
  cause: unknown
): CarbonError | null {
  const known = databaseRefusal(cause);
  if (!known) return null;
  return new CarbonError(
    known.category,
    message
      ? `${message.replace(/[.:]\s*$/, "")}: ${known.message}`
      : known.message,
    cause
  );
}

/** A `CarbonError` as it crosses to the client: its fields, never its cause. */
export type SerializedError<E> =
  E extends CarbonError<infer C>
    ? { category: C; message: string; status: (typeof ERROR_STATUS)[C] }
    : never;

/** A service function's result as a route sends it. */
export type RouteResult<R> = [R] extends [Result<infer T, infer E>]
  ? { data: T; error: null } | { data: null; error: SerializedError<E> }
  : never;

/**
 * The result as a route returns it. React Router replaces an `Error` instance
 * with a bare `Error` (a generic message in production), so the error goes out
 * as a plain object.
 */
export function toResult<T, E extends CarbonError>(
  result: Result<T, E>
): RouteResult<Result<T, E>> {
  if (result.error === null) return result as RouteResult<Result<T, E>>;
  const { category, message, status } = result.error;
  return {
    data: null,
    error: { category, message, status }
  } as RouteResult<Result<T, E>>;
}