Skip to content
Agar0.5.0
API reference

backend

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/agar/backend";

Exports

Section titled “Exports”
Kind Export Description
class AppMethodRefusal An App method’s declared domain refusal. A handler throws it to decline a call; the generated method boundary returns it as a typed AppMethodReply instead of an execution failure. Its message is caller-facing App copy, so it must not carry private data.
type alias AppMethodRefusalCode One of appMethodRefusalCodes.
type alias AppMethodRefusedReply A decoded appMethodRefusedReplySchema value.
type alias AppMethodReply A decoded appMethodReplySchema value; the result is read-only JSON.
constant appBackendRefusalSchema Closed host refusal vocabulary. Private backend messages never reach callers.
constant appBackend Invoke this App’s admitted backend. The App defines its JSON request/result.
constant appMethods Call one of this App’s declared, typed methods through its host. Unlike appBackend, the host knows which method is called, so it can apply the method’s declared effect (for example, allow only read methods to a visitor of a public App).
constant appBackendActorHeader The admitting host overwrites this header from its authenticated principal. App request bodies and incoming browser headers never supply this identity.
constant appBackendComputerHeader The admitting host overwrites this header with the Computer it has verified the caller is admitted to use for this invocation, or omits it when no Computer is bound to the call. App request bodies and incoming browser headers never supply this identity: a backend that needs a Computer scope must read it from here, never from its own request body.
constant appMethodRefusalCodes The closed vocabulary an App method may refuse with. Each code names one caller-visible outcome; the host owns how it is presented (see appMethodRefusalStatus).
constant appMethodRefusalStatus HTTP status for each refusal code, shared by every host and App route.
constant maxAppMethodRefusalMessage Bound on the App-authored refusal message that reaches callers.
constant appMethodRefusedReplySchema A refused call as it crosses the generated method boundary.
constant appMethodReplySchema Every generated App method RPC answers with exactly one of these.

AppMethodRefusalclass

Section titled “AppMethodRefusal”

An App method’s declared domain refusal. A handler throws it to decline a call; the generated method boundary returns it as a typed AppMethodReply instead of an execution failure. Its message is caller-facing App copy, so it must not carry private data.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new AppMethodRefusal(code, message): AppMethodRefusal;
Parameters
Section titled “Parameters”
Parameter Type
code "unavailable" | "invalid" | "conflict" | "forbidden" | "not_found"
message string
Returns
Section titled “Returns”

AppMethodRefusal

Overrides
Section titled “Overrides”
Signature
Error.constructor;

Properties

Section titled “Properties”

code

Section titled “code”
Signature
readonly code: "unavailable" | "invalid" | "conflict" | "forbidden" | "not_found";

AppMethodRefusalCodetype alias

Section titled “AppMethodRefusalCode”
Signature
type AppMethodRefusalCode = (typeof appMethodRefusalCodes)[number];

One of appMethodRefusalCodes.

AppMethodRefusedReplytype alias

Section titled “AppMethodRefusedReply”
Signature
type AppMethodRefusedReply = z.output<typeof appMethodRefusedReplySchema>;

A decoded appMethodRefusedReplySchema value.

AppMethodReplytype alias

Section titled “AppMethodReply”
Signature
type AppMethodReply =
  | Readonly<{
      kind: "ok";
      value: WhistleJsonValue;
    }>
  | AppMethodRefusedReply;

A decoded appMethodReplySchema value; the result is read-only JSON.

appBackendRefusalSchemaconstant

Section titled “appBackendRefusalSchema”
Signature
const appBackendRefusalSchema: ZodObject<
  {
    error: ZodLiteral<"App execution unavailable">;
    reason: ZodEnum<{
      disabled: "disabled";
      exec_isolation_required: "exec_isolation_required";
      execution_not_admitted: "execution_not_admitted";
      artifact_unavailable: "artifact_unavailable";
    }>;
  },
  $strict
>;

Closed host refusal vocabulary. Private backend messages never reach callers.

appBackendconstant

Section titled “appBackend”
Signature
const appBackend: CapabilityContract<{
  request: Promise<WhistleJsonValue>;
}>;

Invoke this App’s admitted backend. The App defines its JSON request/result.

appMethodsconstant

Section titled “appMethods”
Signature
const appMethods: CapabilityContract<{
  call: Promise<WhistleJsonValue>;
}>;

Call one of this App’s declared, typed methods through its host. Unlike appBackend, the host knows which method is called, so it can apply the method’s declared effect (for example, allow only read methods to a visitor of a public App).

appBackendActorHeaderconstant

Section titled “appBackendActorHeader”
Signature
const appBackendActorHeader: "X-Agar-Actor-Id" = "X-Agar-Actor-Id";

The admitting host overwrites this header from its authenticated principal. App request bodies and incoming browser headers never supply this identity.

appBackendComputerHeaderconstant

Section titled “appBackendComputerHeader”
Signature
const appBackendComputerHeader: "X-Agar-Computer-Id" = "X-Agar-Computer-Id";

The admitting host overwrites this header with the Computer it has verified the caller is admitted to use for this invocation, or omits it when no Computer is bound to the call. App request bodies and incoming browser headers never supply this identity: a backend that needs a Computer scope must read it from here, never from its own request body.

appMethodRefusalCodesconstant

Section titled “appMethodRefusalCodes”
Signature
const appMethodRefusalCodes: readonly [
  "invalid",
  "forbidden",
  "not_found",
  "conflict",
  "unavailable",
];

The closed vocabulary an App method may refuse with. Each code names one caller-visible outcome; the host owns how it is presented (see appMethodRefusalStatus).

appMethodRefusalStatusconstant

Section titled “appMethodRefusalStatus”
Signature
const appMethodRefusalStatus: object;

HTTP status for each refusal code, shared by every host and App route.

Type Declaration

Section titled “Type Declaration”
Name Type Default value
invalid 400 400
forbidden 403 403
not_found 404 404
conflict 409 409
unavailable 503 503

maxAppMethodRefusalMessageconstant

Section titled “maxAppMethodRefusalMessage”
Signature
const maxAppMethodRefusalMessage: 500 = 500;

Bound on the App-authored refusal message that reaches callers.

appMethodRefusedReplySchemaconstant

Section titled “appMethodRefusedReplySchema”
Signature
const appMethodRefusedReplySchema: ZodLazy<
  ZodObject<
    {
      kind: ZodLiteral<"refused">;
      code: ZodEnum<{
        unavailable: "unavailable";
        invalid: "invalid";
        conflict: "conflict";
        forbidden: "forbidden";
        not_found: "not_found";
      }>;
      message: ZodString;
    },
    $strict
  >
>;

A refused call as it crosses the generated method boundary.

appMethodReplySchemaconstant

Section titled “appMethodReplySchema”
Signature
const appMethodReplySchema: ZodLazy<
  ZodDiscriminatedUnion<
    [
      ZodObject<
        {
          kind: ZodLiteral<"ok">;
          value: ZodJSONSchema;
        },
        $strict
      >,
      ZodLazy<
        ZodObject<
          {
            kind: ZodLiteral<"refused">;
            code: ZodEnum<{
              unavailable: "unavailable";
              invalid: "invalid";
              conflict: "conflict";
              forbidden: "forbidden";
              not_found: "not_found";
            }>;
            message: ZodString;
          },
          $strict
        >
      >,
    ],
    "kind"
  >
>;

Every generated App method RPC answers with exactly one of these.