@astrale-os/sdk 0.4.19 → 0.5.0-beta.2

package/src/method/context.ts

@@ -1,135 +0,0 @@
-/**
- * `RemoteContext` — what every remote method handler receives at runtime.
- *
- * Assembled by the dispatch pipeline before calling `execute`. Carries the
- * validated params, the resolved auth context, the bound node instance (for
- * non-static methods), the typed dependency container, and a
- * `BoundClientSessionView` to call back into the parent kernel, plus explicit
- * `domain`, `caller`, and `fn` namespaces for identity-sensitive work.
- */
-
-import type { AuthPolicy } from '@astrale-os/kernel-api/routed'
-import type { FnMap, SchemaBoundView } from '@astrale-os/kernel-client'
-import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
-import type { AuthContext } from '@astrale-os/kernel-core'
-import type { Schema } from '@astrale-os/kernel-dsl'
-import type { Defer, Sleep } from '@astrale-os/kernel-server'
-
-import type { FunctionContextApi } from '../auth/function-context.js'
-import type { DomainAuthority } from '../auth/issuer-mint.js'
-import type { Step } from '../step/index.js'
-
-export type { GraphApi } from '@astrale-os/kernel-client/graph'
-
-/**
- * The kernel session a handler holds: a credential-bound view over the parent
- * kernel — the FULL dispatch surface (`call`/`stream`/`binary`/`signal`,
- * `withSchema` typed dispatch, `as` to rebind the acting credential), not just
- * `call`. Name it from `@astrale-os/sdk` instead of reaching into
- * `@astrale-os/kernel-client`. (For the narrow `{ call }` contract — e.g. a
- * tiny test double — see {@link KernelCaller}.)
- *
- */
-export type Kernel = BoundClientSessionView<FnMap>
-
-/** The default handler kernel for one authored domain schema. */
-export type DomainKernel<S extends Schema> = SchemaBoundView<S, FnMap>
-
-/**
- * The `kernel` a handler receives, derived from its declared `auth` policy.
- * The runtime guarantee (see `auth/resolve.ts`) is exact:
- *   - `'required'` (the default) — the dispatcher rejects a credentialless call
- *     before `execute`, so the kernel is ALWAYS present → non-null.
- *   - `'optional'` — a kernel only when a credential was supplied → `… | null`.
- *   - `'public'` — never any inbound credential → `null`. Public handlers that
- *     must touch the graph use `ctx.fn.kernel()` after verifying their upstream.
- *
- * Distributes over a `AuthPolicy` union (e.g. when `auth` is typed but not a
- * literal) to the widened `Kernel | null` — the safe superset, matching the
- * pre-conditional behaviour.
- */
-export type KernelForAuth<
-  TAuth extends AuthPolicy,
-  TKernel extends Kernel = Kernel,
-> = TAuth extends 'public' ? null : TAuth extends 'optional' ? TKernel | null : TKernel
-
-/**
- * The resolved auth context a handler receives, derived from its declared
- * `auth` policy. Mirrors {@link KernelForAuth}: required methods have a
- * verified auth context, optional/public methods encode the nullable cases.
- */
-export type AuthForPolicy<TAuth extends AuthPolicy> = TAuth extends 'public'
-  ? null
-  : TAuth extends 'optional'
-    ? AuthContext | null
-    : AuthContext
-
-export type RemoteEnv = {
-  /** This worker's canonical serving URL. */
-  url: string
-}
-
-export type CallerContext = {
-  /** Issuer of the inbound kernel/peer credential. */
-  iss: string
-  /** Kernel URL associated with this invocation. */
-  url: string
-}
-
-type RemoteBaseContext<
-  TParams,
-  TSelf,
-  TDeps,
-  TKernel = Kernel | null,
-  TAuth extends AuthPolicy = AuthPolicy,
-> = {
-  /** Validated params (Zod-checked against the method's `inputSchema`). */
-  params: TParams
-  /**
-   * Auth context resolved from the inbound delegation credential. Its
-   * nullability follows the method's `auth` policy: non-null for the default
-   * `'required'`, `... | null` for `'optional'`, and `null` for `'public'`.
-   */
-  auth: AuthForPolicy<TAuth>
-  /** Bound node instance — `undefined` for static methods. */
-  self: TSelf
-  /** Typed dependency container injected at server startup. */
-  deps: TDeps
-  /** Local serving metadata. */
-  env: RemoteEnv
-  /**
-   * Credential-bound client to the parent kernel. Domain methods receive a
-   * schema-bound client by default; standalone functions receive the raw
-   * session because they are not owned by a schema class.
-   */
-  kernel: TKernel
-  /** Inbound kernel/peer context. Present only for authenticated invocations. */
-  caller?: CallerContext
-  /** Mint seam for identities THIS DOMAIN issues (`iss` = this worker). */
-  domain: DomainAuthority
-  /** Current function identity tools: grant-bearing credentials and self-bound kernels. */
-  fn: FunctionContextApi
-}
-
-export type RemoteAuthorizeContext<
-  TParams,
-  TSelf,
-  TDeps,
-  TKernel = Kernel | null,
-  TAuth extends AuthPolicy = AuthPolicy,
-> = RemoteBaseContext<TParams, TSelf, TDeps, TKernel, TAuth>
-
-export interface RemoteContext<
-  TParams,
-  TSelf,
-  TDeps,
-  TKernel = Kernel | null,
-  TAuth extends AuthPolicy = AuthPolicy,
-> extends RemoteBaseContext<TParams, TSelf, TDeps, TKernel, TAuth> {
-  /** Durable-shaped step builder. Inline today, replayable by future backends. */
-  step: Step
-  /** Run independent work without making its completion part of this result. */
-  defer: Defer
-  /** Pause execution for a relative duration. Durable hosts may persist the wait. */
-  sleep: Sleep
-}

package/src/method/index.ts

@@ -1,19 +0,0 @@
-export type {
-  AuthForPolicy,
-  DomainKernel,
-  GraphApi,
-  Kernel,
-  KernelForAuth,
-  RemoteAuthorizeContext,
-  RemoteContext,
-} from './context.js'
-export type {
-  RemoteHandler,
-  AnyRemoteHandler,
-  MethodImpl,
-  MethodParams,
-  MethodResult,
-} from './single.js'
-export { remoteMethod } from './single.js'
-export type { ClassMethodsImpl, InterfaceMethodsImpl, SchemaMethodsImpl } from './class.js'
-export { remoteClassMethods, remoteInterfaceMethods } from './class.js'

package/src/method/single.ts

@@ -1,166 +0,0 @@
-/** Authoring helpers for one schema-bound remote method. */
-
-import type { AuthPolicy, RouteBinding } from '@astrale-os/kernel-api/routed'
-import type {
-  MethodClassKeys,
-  ClassMethodConfig,
-  NonSealedMethodKeys,
-  OwnMethodKeys,
-} from '@astrale-os/kernel-core/domain'
-import type { Schema } from '@astrale-os/kernel-dsl'
-
-import type { TypedSelf } from '../dispatch/self.js'
-import type {
-  DomainKernel,
-  Kernel,
-  KernelForAuth,
-  RemoteAuthorizeContext,
-  RemoteContext,
-} from './context.js'
-
-/**
- * Remote method handler. `execute` is optional only for binding stubs; any
- * handler that the dispatcher actually reaches must provide it.
- */
-export type RemoteHandler<
-  TParams,
-  TResult,
-  TSelf,
-  TDeps,
-  TAuth extends AuthPolicy = 'required',
-  TKernel extends Kernel = Kernel,
-> = {
-  /** The handler body. May be async or an async generator (for `output: 'stream'`). */
-  execute?: (
-    ctx: RemoteContext<TParams, TSelf, TDeps, KernelForAuth<TAuth, TKernel>, TAuth>,
-  ) => TResult | Promise<TResult> | AsyncGenerator<TResult>
-  /**
-   * Optional REST binding — attaches a native HTTP route to this method.
-   * Uses the kernel's canonical `RouteBinding` type directly.
-   */
-  route?: RouteBinding
-  /**
-   * Optional anchor URL — marks this method as anchored to a specific host.
-   * May contain `{name}` placeholders matching fields in the input schema.
-   * If absent, the method is ambient (mounts on whatever server loads the domain).
-   */
-  remoteUrl?: string
-  /** Optional human-readable description. Appears in generated docs. */
-  description?: string
-  /**
-   * Authentication policy. Defaults to `'required'` when absent. Captured as a
-   * literal type so it drives `ctx.auth` and {@link KernelForAuth} on the
-   * `execute`/`authorize` context: omit it (or set `'required'`) and both
-   * `ctx.auth` and `ctx.kernel` are non-null; `'optional'` widens them to
-   * `... | null`; `'public'` makes both `null`.
-   */
-  auth?: TAuth
-  /**
-   * Optional business authorization after auth/_self resolution. Kernel
-   * has_perm checks remain authoritative; this is additive gating.
-   */
-  authorize?: (
-    ctx: RemoteAuthorizeContext<TParams, TSelf, TDeps, KernelForAuth<TAuth, TKernel>, TAuth>,
-  ) => void | Promise<void>
-}
-
-// Post-binding indexes erase the concrete auth policy; authoring remains checked
-// at `remoteMethod`, while dispatcher/build-spec only need a policy-neutral bag.
-// oxlint-disable no-explicit-any
-export type AnyRemoteHandler = Omit<
-  RemoteHandler<any, any, any, any, AuthPolicy, Kernel>,
-  'authorize' | 'execute'
-> & {
-  execute?: (ctx: any) => any
-  authorize?: (ctx: any) => void | Promise<void>
-}
-// oxlint-enable no-explicit-any
-
-// Compile-time guard: every auth policy must fit the erased handler bag.
-type _AssertTrueH<T extends true> = T
-type _HandlerFitsBag<D> = D extends AnyRemoteHandler ? true : false
-export type _MethodPolicyBagGuards = [
-  _AssertTrueH<_HandlerFitsBag<RemoteHandler<unknown, unknown, unknown, unknown, 'public'>>>,
-  _AssertTrueH<_HandlerFitsBag<RemoteHandler<unknown, unknown, unknown, unknown, 'optional'>>>,
-  _AssertTrueH<_HandlerFitsBag<RemoteHandler<unknown, unknown, unknown, unknown, 'required'>>>,
-]
-
-/**
- * Fully typed method implementation — resolves params/result/self from the
- * schema, wraps in `RemoteHandler` with deps.
- */
-export type MethodImpl<
-  S extends Schema,
-  K extends MethodClassKeys<S> & string,
-  M extends string,
-  TDeps = unknown,
-  TAuth extends AuthPolicy = 'required',
-> =
-  ClassMethodConfig<S, K, M> extends {
-    params: infer P
-    result: infer R
-    self: unknown
-    isStatic: infer St
-  }
-    ? RemoteHandler<
-        P,
-        R,
-        St extends true ? undefined : TypedSelf<S['classes'][K], S>,
-        TDeps,
-        TAuth,
-        DomainKernel<S>
-      >
-    : never
-
-/**
- * `MethodParams` / `MethodResult` — a handler types its `params` as
- * `MethodParams<typeof schema, 'Def', 'method'>` and its return as
- * `MethodResult<…>`, so it never re-declares (and can't drift from) the schema.
- * Resolved from whichever def — CLASS or INTERFACE — declares the method.
- */
-export type { MethodParams, MethodResult } from '@astrale-os/kernel-core/domain'
-
-type ImplementableMethodName<S extends Schema, K extends MethodClassKeys<S> & string> = (
-  | OwnMethodKeys<S, K>
-  | NonSealedMethodKeys<S, K>
-) &
-  string
-
-/**
- * Identity helper for authoring one remote method with full schema-driven typing.
- *
- * Two-form calling convention:
- *  - `remoteMethod<TDeps>()` — curried form; captures deps type, returns a
- *     per-schema helper. Use when you want deps typed.
- *  - `remoteMethod(schema, className, methodName, impl)` — direct form with
- *     `unknown` deps.
- */
-export function remoteMethod<TDeps>(): <
-  S extends Schema,
-  K extends MethodClassKeys<S> & string,
-  M extends ImplementableMethodName<S, K>,
-  TAuth extends AuthPolicy = 'required',
->(
-  schema: S,
-  className: K,
-  methodName: M,
-  impl: MethodImpl<S, K, M, TDeps, TAuth>,
-) => MethodImpl<S, K, M, TDeps, TAuth>
-export function remoteMethod<
-  S extends Schema,
-  K extends MethodClassKeys<S> & string,
-  M extends ImplementableMethodName<S, K>,
-  TAuth extends AuthPolicy = 'required',
->(
-  schema: S,
-  className: K,
-  methodName: M,
-  impl: MethodImpl<S, K, M, unknown, TAuth>,
-): MethodImpl<S, K, M, unknown, TAuth>
-export function remoteMethod(...args: unknown[]) {
-  if (args.length === 0) {
-    return (...innerArgs: unknown[]) => innerArgs[3]
-  }
-
-  return args[3]
-}