@owlmeans/entrypoint 0.1.18-rc.4 → 0.1.18-rc.40

package/src/materialize.ts

@@ -0,0 +1,43 @@
+import { entrypoint } from './entrypoint.js'
+import type { CommonEntrypointOptions, Filter, EntrypointProtocolDeclaration, MaterializedEntrypoint } from './types.js'
+
+const filterOf = (protocol: EntrypointProtocolDeclaration): Filter | undefined => {
+  const request = protocol.contract?.requestSchemas
+  const response = protocol.contract?.responseSchemas
+
+  if (request == null && response == null) return undefined
+
+  return {
+    body: request?.body == null ? undefined : structuredClone(request.body),
+    params: request?.params == null ? undefined : structuredClone(request.params),
+    query: request?.query == null ? undefined : structuredClone(request.query),
+    headers: request?.headers == null ? undefined : structuredClone(request.headers),
+    // Fastify requires response serializers to be keyed by a status code. A protocol's
+    // ordinary response has no explicit outcome, so it is the normal successful 200 reply.
+    response: response == null ? undefined : {
+      ...(response.default == null ? {} : { 200: structuredClone(response.default) }),
+      ...Object.fromEntries(Object.entries(response.byStatus ?? {}).map(([status, schema]) => [
+        status, structuredClone(schema),
+      ])),
+    },
+  }
+}
+
+const optionsOf = (protocol: EntrypointProtocolDeclaration): CommonEntrypointOptions => ({
+  sticky: protocol.sticky,
+  guards: [...protocol.guards],
+  gate: protocol.gate?.alias,
+  gateParams: protocol.gate == null ? undefined : [...protocol.gate.params],
+  filter: filterOf(protocol),
+})
+
+/**
+ * Make a local, mutable registration from a shared declaration.  The protocol is never mutated;
+ * guards, route resolution and handlers belong exclusively to this materialized entrypoint.
+ */
+export const materializeEntrypoint = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol,
+): MaterializedEntrypoint<Protocol> => Object.assign(
+  entrypoint({ route: { ...protocol.route.route } }, optionsOf(protocol)),
+  { protocol },
+)

package/src/protocol.ts

@@ -0,0 +1,191 @@
+import type { EntrypointReference } from '@owlmeans/context'
+import type { JSONSchemaType, AnySchemaObject } from 'ajv'
+import type { RouteModel } from '@owlmeans/route'
+import type { AnyShapeSource } from './types.local.js'
+import type { EntrypointContract, EntrypointGate, EntrypointOptions, EntrypointProtocol, EntrypointProtocolDeclaration, EntrypointSchema, EntrypointTree, OpenRequest, OpenValue, RegisteredEntrypoint, RequestFromSources, RequestShape, RequestSources, RuntimeResponseSchemas, ShapeSource, Typed } from './types.js'
+
+export const schema = <T>(value: JSONSchemaType<T>): EntrypointSchema<T> =>
+  value as EntrypointSchema<T>
+
+/**
+ * Supplies type information where a response has no runtime schema, or attaches a type to an
+ * otherwise untyped schema literal at the declaration boundary.
+ */
+export function typed<T>(): Typed<T>
+export function typed<T>(schema: JSONSchemaType<T>): Typed<T>
+export function typed<T>(schema?: JSONSchemaType<T>): Typed<T> {
+  return schema == null
+    ? { kind: 'entrypoint-type' }
+    : { kind: 'entrypoint-type', schema }
+}
+
+const schemaOf = (source: AnyShapeSource | undefined): AnySchemaObject | undefined => {
+  if (source == null) return undefined
+  const schema = 'kind' in source && source.kind === 'entrypoint-type'
+    ? source.schema
+    : source
+
+  return schema == null ? undefined : structuredClone(schema)
+}
+
+const responseSchemasOf = (source: AnyShapeSource | undefined): RuntimeResponseSchemas | undefined => {
+  const schema = schemaOf(source)
+  return schema == null ? undefined : { default: schema }
+}
+
+/**
+ * Declare an exact request and response.  The primary overload means a body request; use
+ * `contract.request` for independently-shaped request sections.
+ */
+export function contract(): EntrypointContract<{}, undefined>
+export function contract<Response>(response: ShapeSource<Response>): EntrypointContract<{}, Response>
+export function contract<Body extends OpenValue, Response>(
+  body: ShapeSource<Body>, response: ShapeSource<Response>
+): EntrypointContract<{ body: Body }, Response>
+export function contract(
+  first?: AnyShapeSource, second?: AnyShapeSource
+): EntrypointContract<RequestShape, OpenValue> {
+  const body = second == null ? undefined : first
+  const response = second ?? first
+
+  return {
+    kind: 'entrypoint-contract',
+    requestSchemas: { body: schemaOf(body) },
+    responseSchemas: responseSchemasOf(response),
+  }
+}
+
+export namespace contract {
+  export function request<Sources extends RequestSources, Response>(
+    request: Sources,
+    response: ShapeSource<Response>
+  ): EntrypointContract<RequestFromSources<Sources>, Response> {
+    return {
+      kind: 'entrypoint-contract',
+      requestSchemas: {
+        body: schemaOf(request.body),
+        params: schemaOf(request.params),
+        query: schemaOf(request.query),
+        headers: schemaOf(request.headers),
+      },
+      responseSchemas: responseSchemasOf(response),
+    }
+  }
+}
+
+const guardsOf = (guards: EntrypointOptions['guards']): readonly string[] => guards == null
+  ? []
+  : typeof guards === 'string' ? [guards] : [...guards]
+
+const gateOf = (gate: EntrypointOptions['gate']): EntrypointProtocol['gate'] => gate == null
+  ? undefined
+  : {
+      alias: gate.alias,
+      params: gate.params == null ? [] : typeof gate.params === 'string' ? [gate.params] : [...gate.params],
+    }
+
+/** Create an immutable protocol declaration from a route and its contract. */
+export const protocol = <Request extends RequestShape, Response>(
+  route: RouteModel,
+  entrypointContract: EntrypointContract<Request, Response>,
+  options?: EntrypointOptions
+): EntrypointProtocol<Request, Response> => Object.freeze({
+  kind: 'entrypoint-protocol' as const,
+  alias: route.route.alias,
+  route: Object.freeze({ route: Object.freeze({ ...route.route }) }),
+  contract: entrypointContract,
+  sticky: options?.sticky ?? false,
+  guards: Object.freeze(guardsOf(options?.guards)),
+  gate: gateOf(options?.gate),
+})
+
+export const openProtocol = (
+  route: RouteModel,
+  options?: EntrypointOptions
+): EntrypointProtocol<OpenRequest, OpenValue> => Object.freeze({
+  kind: 'entrypoint-protocol' as const,
+  alias: route.route.alias,
+  route: Object.freeze({ route: Object.freeze({ ...route.route }) }),
+  sticky: options?.sticky ?? false,
+  guards: Object.freeze(guardsOf(options?.guards)),
+  gate: gateOf(options?.gate),
+})
+
+export const entrypointRef = <Request extends RequestShape = OpenRequest, Response = OpenValue>(
+  alias: string
+): EntrypointReference<RegisteredEntrypoint<Request, Response>> => ({ alias })
+
+export const aliasOf = (reference: EntrypointReference | string): string =>
+  typeof reference === 'string' ? reference : reference.alias
+
+export const isEntrypointProtocol = (value: object): value is EntrypointProtocolDeclaration =>
+  'kind' in value && value.kind === 'entrypoint-protocol'
+
+/** Flatten an exported protocol tree for a layer-specific materializer. */
+export const protocols = (tree: EntrypointTree): EntrypointProtocolDeclaration[] => {
+  const result: EntrypointProtocolDeclaration[] = []
+
+  const visit = (node: EntrypointTree): void => {
+    Object.values(node).forEach((entry) => {
+      if (isEntrypointProtocol(entry)) {
+        result.push(entry)
+      } else {
+        visit(entry)
+      }
+    })
+  }
+
+  visit(tree)
+  return result
+}
+
+/**
+ * Rebuild an immutable protocol tree while transforming its declarations.
+ *
+ * Protocol consumers keep addressing declarations by their exported tree path; a cross-cutting
+ * concern such as a coguard therefore never needs to flatten the tree and recover declarations
+ * by alias.
+ */
+export const mapProtocols = <Tree extends EntrypointTree>(
+  tree: Tree,
+  mapper: (protocol: EntrypointProtocolDeclaration) => EntrypointProtocolDeclaration,
+): Tree => Object.freeze(Object.fromEntries(
+  Object.entries(tree).map(([key, entry]) => [
+    key,
+    isEntrypointProtocol(entry) ? mapper(entry) : mapProtocols(entry, mapper),
+  ])
+)) as Tree
+
+/** Resolve the gates a protocol inherits through its route parents without materializing it. */
+export const gatesOf = (
+  protocol: EntrypointProtocolDeclaration,
+  tree: EntrypointTree,
+): readonly EntrypointGate[] => {
+  const byAlias = new Map(protocols(tree).map(candidate => [candidate.alias, candidate]))
+  const result: EntrypointGate[] = []
+  const visited = new Set<string>()
+  let current: EntrypointProtocolDeclaration | undefined = protocol
+
+  while (current != null && !visited.has(current.alias)) {
+    visited.add(current.alias)
+    if (current.gate != null && !result.some(gate => gate.alias === current!.gate!.alias)) {
+      result.push(current.gate)
+    }
+    current = current.route.route.parent == null
+      ? undefined
+      : byAlias.get(current.route.route.parent)
+  }
+
+  return result
+}
+
+/** Clone an immutable protocol while preserving its request/response pair. */
+export const decorateEntrypoint = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol,
+  options: EntrypointOptions
+): Protocol => Object.freeze({
+  ...protocol,
+  sticky: options.sticky ?? protocol.sticky,
+  guards: options.guards == null ? protocol.guards : guardsOf(options.guards),
+  gate: options.gate == null ? protocol.gate : gateOf(options.gate),
+})

package/src/types.local.ts

@@ -0,0 +1,24 @@
+import type { JSONSchemaType, AnySchemaObject } from 'ajv'
+import type { EntrypointSchema, OpenValue, RequestShape, Typed } from './types.js'
+
+export interface TypeToken {
+  readonly kind: 'entrypoint-type'
+  readonly schema?: AnySchemaObject
+}
+
+export declare const entrypointSchemaType: unique symbol
+
+export type AnyShapeSource = AnySchemaObject | TypeToken
+
+export type SourceValue<Source> =
+  Source extends Typed<infer Value> ? Value
+    : Source extends EntrypointSchema<infer Value> ? Value
+      : Source extends JSONSchemaType<infer Value>
+        ? Value extends OpenValue ? Value : OpenValue
+        : OpenValue
+
+export type UrlRequest<Request extends RequestShape> =
+  (Request extends { params: infer Params } ? { params: Params }
+    : Request extends { params?: infer Params } ? { params?: Params } : {})
+  & (Request extends { query: infer Query } ? { query: Query }
+    : Request extends { query?: infer Query } ? { query?: Query } : {})

package/src/types.ts

@@ -1,29 +1,47 @@
-import type { CommonRouteModel } from '@owlmeans/route'
-import type { InitializedService, LazyService, BasicEntrypoint } from '@owlmeans/context'
-import type { AnySchemaObject } from 'ajv'
+import type { ResolvedServiceRoute, RouteAddress, RouteModel, RouteProtocol } from '@owlmeans/route'
+import type { InitializedService, LazyService, BasicEntrypoint, EntrypointReference } from '@owlmeans/context'
+import type { AnySchemaObject, JSONSchemaType } from 'ajv'
 import type { EntrypointOutcome } from './consts.js'
 import type { Auth } from '@owlmeans/auth'
 
+import type { AnyShapeSource, entrypointSchemaType, SourceValue, TypeToken, UrlRequest } from './types.local.js'
+import type { createFilterHelper } from './filter.js'
+
+/**
+ * A URL unit: an immutable route declaration plus what guards, gates and schemas it answers under.
+ *
+ * Nothing here is rewritten once declared. Every address question — segment, path, mount, service,
+ * host — is a question about the declaration asked against the context the entrypoint is registered
+ * in, so the same declaration answers differently in a client and in a server without being touched.
+ */
 export interface CommonEntrypoint extends BasicEntrypoint {
-  route: CommonRouteModel
+  route: RouteModel
   /**
    * @property {boolean} - if true — router attaches this entrypoint unconditionally
    * @default false
    */
   sticky: boolean
-  filter?: Filter
+  /** The guards declared on this entrypoint alone — see `getGuards()` for the inherited set. */
   guards?: string[]
   gate?: string
   gateParams?: string | string[]
+  filter?: Filter
   handle?: EntrypointHandler
-  getAlias: () => string
-  getPath: () => string
-  getParentAlias: () => string | null
-  hasParent: () => boolean
-  resolve: <M extends CommonEntrypoint>() => Promise<M>
-  getParent: <M extends CommonEntrypoint>() => M
-  setService: (service: string) => void
+
+  /** The segment this entrypoint contributes under its parent. */
+  segment: () => string
+  /** Every ancestor's segment, then this one. */
+  path: () => string
+  /** `base` + `path()` — what a server mounts and a client requests. */
+  mount: () => string
+  service: () => ResolvedServiceRoute
+  address: () => RouteAddress
+  /** Does this entrypoint belong to the service its context IS? */
+  isLocal: () => boolean
+  parent: () => CommonEntrypoint | null
+  /** Own guards and every ancestor's, deduped. Recomputed on each call. */
   getGuards: () => string[]
+  /** Own gate and every ancestor's, as `[gate, params]`. Recomputed on each call. */
   getGates: () => [string, string[]][]
 }
 
@@ -47,6 +65,17 @@ export interface EntrypointAssert {
 export interface AbstractRequest<T extends {} = {}> {
   alias: string
   auth?: Auth
+  /**
+   * The organization entity this request acts for, resolved from `auth.entitySlug` once, at the
+   * server boundary.
+   *
+   * The slug on the token is renameable and therefore unusable as a key; `entity.id` is the stable
+   * value that records, grants and minted infrastructure names are keyed by. Resolving it here —
+   * rather than in each handler — is what keeps a rename from meaning a sweep of every call site,
+   * and it is absent whenever no resolver is registered (an implementation that has no notion of
+   * an organization store), so consumers must handle that rather than assume it.
+   */
+  entity?: ResolvedEntity
   params: Record<string, string | number | undefined | null> | Partial<T>
   body?: Record<string, any> | Partial<T>
   headers: Record<string, string[] | string | undefined>
@@ -66,6 +95,21 @@ export interface AbstractRequest<T extends {} = {}> {
   signal?: AbortSignal
 }
 
+/**
+ * An organization entity as request handlers see it: the stable id to key by, the current slug to
+ * compose user-facing names from, and the frozen key that external systems already know it under.
+ */
+export interface ResolvedEntity {
+  id: string
+  slug: string
+  /**
+   * The identifier this organization is known by in systems whose names cannot be rewritten —
+   * an IAM realm, an object-storage prefix, a cluster object. Minted once and never recomputed,
+   * so it stays valid across every later rename.
+   */
+  iamKey: string
+}
+
 export interface AbstractResponse<T> {
   responseProvider?: any
   value?: T,
@@ -98,3 +142,209 @@ export interface Filter {
   response?: AnySchemaObject
   headers?: AnySchemaObject
 }
+
+/**
+ * How a call to an entrypoint is actually carried.
+ *
+ * The transport is chosen by the route's protocol, so a consumer always writes `ep.call(...)` and
+ * never learns which built-in or package-owned carrier handled it. An
+ * application binds a protocol by registering a transport service under `transportAlias(protocol)`.
+ */
+export interface EntrypointTransport extends InitializedService {
+  readonly protocol: RouteProtocol
+  handle: EntrypointHandler
+}
+
+/** A deliberately broad value used only by declarations without an I/O contract. */
+export type OpenValue = object | string | number | boolean | bigint | null | undefined
+
+/** The four independent request sections an entrypoint may declare. */
+export interface RequestShape {
+  body?: OpenValue
+  params?: object
+  query?: object
+  headers?: object
+}
+
+export interface RuntimeRequestSchemas {
+  body?: AnySchemaObject
+  params?: AnySchemaObject
+  query?: AnySchemaObject
+  headers?: AnySchemaObject
+}
+
+export interface RuntimeResponseSchemas {
+  default?: AnySchemaObject
+  byStatus?: Readonly<Record<number, AnySchemaObject>>
+}
+
+/** The runtime schemas and compile-time request/response pair attached to one protocol. */
+export interface EntrypointContract<Request extends RequestShape, Response> {
+  readonly kind: 'entrypoint-contract'
+  readonly requestSchemas: RuntimeRequestSchemas
+  readonly responseSchemas?: RuntimeResponseSchemas
+  readonly requestType?: Request
+  readonly responseType?: Response
+}
+
+/** Runtime fields common to every protocol, regardless of its compile-time request/reply pair. */
+export interface EntrypointProtocolDeclaration {
+  readonly kind: 'entrypoint-protocol'
+  readonly alias: string
+  readonly route: RouteModel
+  readonly contract?: Pick<EntrypointContract<RequestShape, OpenValue>,
+    'kind' | 'requestSchemas' | 'responseSchemas'>
+  readonly sticky: boolean
+  readonly guards: readonly string[]
+  readonly gate?: {
+    readonly alias: string
+    readonly params: readonly string[]
+  }
+}
+
+/** A context-bound entrypoint made from an immutable protocol declaration. */
+export type MaterializedEntrypoint<Protocol extends EntrypointProtocolDeclaration> = CommonEntrypoint & {
+  readonly protocol: Protocol
+}
+
+/** The request accepted by a declaration that intentionally supplies no contract. */
+export interface OpenRequest {
+  body?: object
+  params?: object
+  query?: object
+  headers?: object
+}
+
+/** Addressing and transport controls are never part of an entrypoint's payload contract. */
+export interface CallOptions {
+  auth?: Auth
+  host?: string
+  base?: string | boolean
+  unsecure?: boolean
+  timeout?: number
+  signal?: AbortSignal
+}
+
+/** A type-only contract source, optionally paired with an AJV schema. */
+export type Typed<T> = TypeToken & { readonly value?: T }
+
+/**
+ * A JSON schema carrying the model type it validates.  Use `schema<Model>(...)` once beside the
+ * model; every protocol that consumes it then infers the model without another generic.
+ */
+export type EntrypointSchema<T> = JSONSchemaType<T> & {
+  readonly [entrypointSchemaType]: T
+}
+
+/** A schema or an explicit type-only source for one request/response value. */
+export type ShapeSource<T> = EntrypointSchema<T> | JSONSchemaType<T> | Typed<T>
+
+export interface RequestSources {
+  body?: AnyShapeSource
+  params?: AnyShapeSource
+  query?: AnyShapeSource
+  headers?: AnyShapeSource
+}
+
+/** An access gate declared by a protocol, including inherited parent declarations. */
+export interface EntrypointGate {
+  readonly alias: string
+  readonly params: readonly string[]
+}
+
+export type RequestFromSources<Sources extends RequestSources> =
+  (Sources extends { body: infer Source } ? { body: SourceValue<Source> } : {})
+  & (Sources extends { params: infer Source } ? { params: SourceValue<Source> } : {})
+  & (Sources extends { query: infer Source } ? { query: SourceValue<Source> } : {})
+  & (Sources extends { headers: infer Source } ? { headers: SourceValue<Source> } : {})
+
+export interface EntrypointOptions {
+  sticky?: boolean
+  guards?: string | readonly string[]
+  gate?: {
+    alias: string
+    params?: string | readonly string[]
+  }
+}
+
+export interface EntrypointResult<Response> {
+  value: Response
+  outcome: EntrypointOutcome
+}
+
+export type CallArguments<Request extends RequestShape> = {} extends Request
+  ? [request?: Request & CallOptions]
+  : [request: Request & CallOptions]
+
+export type UrlArguments<Request extends RequestShape> = {} extends UrlRequest<Request>
+  ? [request?: UrlRequest<Request> & CallOptions]
+  : [request: UrlRequest<Request> & CallOptions]
+
+export interface EntrypointRequestMeta {
+  alias: string
+  auth?: Auth
+  entity?: ResolvedEntity
+  path: string
+  canceled?: boolean
+  cancel?: () => void
+}
+
+/**
+ * A protocol request at an implementation boundary.
+ *
+ * Transport metadata and empty request sections remain available to handlers; a declared section
+ * then refines that base shape to its protocol contract.
+ */
+export type HandlerRequest<Request extends RequestShape> = AbstractRequest & Request & EntrypointRequestMeta
+
+/**
+ * An immutable shared declaration.  Its inherited reference type is what gives a context lookup
+ * the exact registered entrypoint type without a consumer-supplied generic.
+ */
+export interface EntrypointProtocol<
+  Request extends RequestShape = RequestShape,
+  Response = OpenValue,
+> extends EntrypointProtocolDeclaration, EntrypointReference<RegisteredEntrypoint<Request, Response>> {
+  readonly contract?: EntrypointContract<Request, Response>
+}
+
+/** The context-bound counterpart of an immutable protocol declaration. */
+export interface RegisteredEntrypoint<Request extends RequestShape, Response> extends BasicEntrypoint {
+  readonly protocol: EntrypointProtocol<Request, Response>
+  call: (...args: CallArguments<Request>) => Promise<Response>
+  invoke: (...args: CallArguments<Request>) => Promise<EntrypointResult<Response>>
+  url: (...args: UrlArguments<Request>) => Promise<string>
+  validate: (...args: CallArguments<Request>) => Promise<boolean>
+}
+
+export type RequestOf<Protocol extends EntrypointProtocolDeclaration> = Protocol extends EntrypointProtocol<infer Request, infer _Response>
+  ? Request
+  : OpenRequest
+
+export type ResponseOf<Protocol extends EntrypointProtocolDeclaration> = Protocol extends EntrypointProtocol<infer _Request, infer Response>
+  ? Response
+  : OpenValue
+
+export type BodyOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { body: infer Body }
+  ? Body
+  : OpenValue
+
+export type ParamsOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { params: infer Params }
+  ? Params
+  : object
+
+export type QueryOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { query: infer Query }
+  ? Query
+  : object
+
+export type HeadersOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { headers: infer Headers }
+  ? Headers
+  : object
+
+export type CallRequestOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> & CallOptions
+
+export interface EntrypointTree {
+  readonly [key: string]: EntrypointProtocolDeclaration | EntrypointTree
+}
+
+export type FilterHelper = ReturnType<typeof createFilterHelper>

package/src/utils/entrypoint.ts

@@ -1,4 +1,4 @@
 import { CommonEntrypoint } from '../types.js'
 
 export const isEntrypoint = (obj: object): obj is CommonEntrypoint =>
-  '_entrypoint' in obj || '_module' in obj
+  '_entrypoint' in obj

package/src/utils/types.ts

@@ -1,6 +1,6 @@
-import { CommonRouteModel } from '@owlmeans/route'
+import { RouteModel } from '@owlmeans/route'
 import { CommonEntrypointOptions } from '../types.js'
 
 export interface CreateEntrypointSignature<M> {
-  (route: CommonRouteModel, opts?: CommonEntrypointOptions): M,
+  (route: RouteModel, opts?: CommonEntrypointOptions): M,
 }

package/src/utils.ts

@@ -0,0 +1,5 @@
+/**
+ * Service alias a transport registers under. The default protocol is the web one, so an application
+ * that binds nothing keeps talking HTTP.
+ */
+export const transportAlias = (protocol: string = 'http') => `transport:${protocol}`