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

package/src/protocol.ts

@@ -0,0 +1,39 @@
+import { materializeEntrypoint, protocols } from '@owlmeans/entrypoint'
+import type { EntrypointProtocolDeclaration, EntrypointTree } from '@owlmeans/entrypoint'
+import { bindMaterializedEntrypoint } from './entrypoint.js'
+import type {
+  ClientEntrypointOptions, ClientProtocolEntrypoint, RefedEntrypointHandler,
+} from './types.js'
+
+/** Bind a shared protocol to the client context without changing the declaration itself. */
+export const bind = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol,
+  options?: ClientEntrypointOptions,
+): ClientProtocolEntrypoint<Protocol> => {
+  const bound = Object.assign(bindMaterializedEntrypoint(
+    materializeEntrypoint(protocol),
+    undefined,
+    options,
+  ), { protocol })
+
+  return bound as ClientProtocolEntrypoint<Protocol>
+}
+
+/** Materialize every protocol in an exported declaration tree for a browser context. */
+export const bindAll = (tree: EntrypointTree): ClientProtocolEntrypoint<EntrypointProtocolDeclaration>[] =>
+  protocols(tree).map(protocol => bind(protocol))
+
+/** Bind a frontend protocol to the component that renders it. */
+export const bindScreen = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol,
+  handler: RefedEntrypointHandler,
+  options?: ClientEntrypointOptions,
+): ClientProtocolEntrypoint<Protocol> => {
+  const bound = Object.assign(bindMaterializedEntrypoint(
+    materializeEntrypoint(protocol),
+    handler,
+    options,
+  ), { protocol })
+
+  return bound as ClientProtocolEntrypoint<Protocol>
+}

package/src/types.ts

@@ -1,18 +1,62 @@
 import type { ClientRouteModel, ClientRouteOptions } from '@owlmeans/client-route'
-import type { AbstractRequest, AbstractResponse, CommonEntrypoint, CommonEntrypointOptions, EntrypointHandler, EntrypointOutcome } from '@owlmeans/entrypoint'
+import type {
+  AbstractRequest, CommonEntrypoint, CommonEntrypointOptions, EntrypointHandler,
+  EntrypointOutcome, EntrypointProtocolDeclaration, RegisteredEntrypoint, RequestOf,
+} from '@owlmeans/entrypoint'
 
 export interface ClientEntrypoint<T = {}, R extends ClientRequest = ClientRequest> extends CommonEntrypoint {
   route: ClientRouteModel
+  /**
+   * Address the entrypoint and resolve to what it answered. The reply's error is thrown, so a
+   * caller that only needs the value never inspects an outcome.
+   */
   call: EntrypointCall<T, R>
+  /**
+   * The same round trip as {@link ClientEntrypoint.call}, resolving to the value AND the outcome.
+   * Use it only where the outcome decides what happens next.
+   */
+  invoke: EntrypointInvoke<T, R>
+  /**
+   * Build the URL this entrypoint addresses, with `:params` filled in and the query appended.
+   * Absolute when the route belongs to another service, or when `absolute` is asked for.
+   */
+  url: EntrypointUrl<R>
   validate: EntrypointFilter<R>
-  getPath: (partial?: boolean) => string
   request: (request?: Partial<R>) => R
 }
 
+/**
+ * The context-bound client view of a protocol.  Unlike the legacy `ClientEntrypoint` generic,
+ * its request and reply types are read directly from the declaration and cannot be replaced at a
+ * call site.
+ */
+export type ClientProtocolEntrypoint<Protocol extends EntrypointProtocolDeclaration> =
+  Omit<ClientEntrypoint, 'call' | 'invoke' | 'url' | 'validate' | 'request'>
+  & RegisteredEntrypoint<RequestOf<Protocol>, import('@owlmeans/entrypoint').ResponseOf<Protocol>>
+  & {
+    readonly protocol: Protocol
+  }
+
 export interface EntrypointCall<T, Req extends ClientRequest = ClientRequest> {
-  <
-    Type extends T, R extends Req = Req, P extends AbstractResponse<Type> = AbstractResponse<Type>
-  >(req?: Partial<R>, res?: P): Promise<[Type, EntrypointOutcome]>
+  <Type extends T, R extends Req = Req>(req?: Partial<R>): Promise<Type>
+}
+
+export interface EntrypointInvoke<T, Req extends ClientRequest = ClientRequest> {
+  <Type extends T, R extends Req = Req>(req?: Partial<R>): Promise<EntrypointReply<Type>>
+}
+
+export interface EntrypointReply<T> {
+  value: T
+  outcome: EntrypointOutcome
+}
+
+export interface EntrypointUrl<Req extends ClientRequest = ClientRequest> {
+  <R extends Req = Req>(req?: Partial<R>, opts?: EntrypointUrlOptions): Promise<string>
+}
+
+export interface EntrypointUrlOptions {
+  /** Force a fully qualified URL even when the route belongs to the current service. */
+  absolute?: boolean
 }
 
 export interface EntrypointFilter<Req extends AbstractRequest = AbstractRequest> {
@@ -20,14 +64,9 @@ export interface EntrypointFilter<Req extends AbstractRequest = AbstractRequest>
 }
 
 export interface ClientRequest<T extends {} = {}> extends AbstractRequest<T> {
-  full?: boolean
 }
 
 export interface ClientEntrypointOptions extends CommonEntrypointOptions {
-  /**
-   * Force entrypoint to be elevated even if it is already elevated
-   */
-  force?: boolean
   routeOptions?: ClientRouteOptions
   validateOnCall?: boolean
 }
@@ -36,6 +75,6 @@ export interface EntrypointRef<T, R extends AbstractRequest = AbstractRequest> {
   ref?: ClientEntrypoint<T, R>
 }
 
-export interface RefedEntrypointHandler<T, R extends AbstractRequest = AbstractRequest> {
+export interface RefedEntrypointHandler<T = {}, R extends AbstractRequest = AbstractRequest> {
   (ref: EntrypointRef<T, R>): EntrypointHandler
 }

package/src/utils/entrypoint.ts

@@ -1,12 +1,11 @@
 import Ajv from 'ajv'
 import type { ErrorObject } from 'ajv'
-import type { EntrypointFilter, ClientEntrypointOptions } from '../types.js'
+import type { EntrypointFilter } from '../types.js'
 import { ClientValidationError } from '../errors.js'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
-import type { EntrypointRef, RefedEntrypointHandler } from '../types.js'
+import type { EntrypointRef } from '../types.js'
 import formatsPlugin from 'ajv-formats'
 
-export { entrypoint as makeBasicEntrypoint } from '@owlmeans/entrypoint'
 export { isEntrypoint } from '@owlmeans/entrypoint/utils'
 
 const ajv = new Ajv({ strict: false })
@@ -50,17 +49,3 @@ export const validate: <T, R extends AbstractRequest = AbstractRequest>(ref: Ent
 
     return true
   }
-
-export const normalizeHelperParams = <T, R extends AbstractRequest = AbstractRequest>(
-  handler?: RefedEntrypointHandler<T, R> | ClientEntrypointOptions | boolean,
-  opts?: ClientEntrypointOptions | boolean
-): [RefedEntrypointHandler<T, R> | undefined, ClientEntrypointOptions | undefined] => {
-  if (typeof handler !== 'function' && handler != null) {
-    opts = handler as ClientEntrypointOptions | boolean
-    handler = undefined
-  }
-
-  opts = typeof opts === 'boolean' ? { validateOnCall: opts } : opts
-
-  return [handler, opts]
-}

package/src/utils/handler.ts

@@ -1,15 +1,17 @@
 import type { ApiClient } from '@owlmeans/api'
 import { DEFAULT_KEY } from '@owlmeans/client-config'
 import type { ClientConfig, ClientContext } from '@owlmeans/client-context'
-import type { AbstractRequest, EntrypointHandler } from '@owlmeans/entrypoint'
-import { EntrypointOutcome, provideResponse } from '@owlmeans/entrypoint'
-import type { ClientEntrypoint, EntrypointCall, ClientEntrypointOptions, EntrypointRef, ClientRequest } from '../types.js'
+import type { AbstractRequest, EntrypointHandler, EntrypointTransport } from '@owlmeans/entrypoint'
+import { EntrypointOutcome, provideResponse, transportAlias } from '@owlmeans/entrypoint'
+import type { ClientEntrypoint, EntrypointInvoke, EntrypointUrlOptions, ClientEntrypointOptions, EntrypointRef, ClientRequest } from '../types.js'
 import { validate } from './entrypoint.js'
 import { extractParams } from '@owlmeans/client-route'
-import { PARAM } from '@owlmeans/route'
+import { PARAM, RouteMethod, RouteProtocols } from '@owlmeans/route'
 import { stringify } from 'qs'
 import { assertContext } from '@owlmeans/context'
 import { makeSecurityHelper } from '@owlmeans/config'
+import { ENTRYPOINT_FAILURE_SERVICE } from '../failure.js'
+import type { EntrypointFailureService } from '../failure.js'
 
 type Config = ClientConfig
 interface Context<C extends Config = Config> extends ClientContext<C> { }
@@ -25,13 +27,23 @@ export const apiHandler: <
   }
 
   const ep = context.entrypoint<ClientEntrypoint>(req.alias)
-  const route = await ep.route.resolve<Config, Context>(context)
 
-  let alias: string | undefined = typeof context.cfg.webService === 'string'
+  // A route names the protocol it answers on. Whatever is bound under that protocol takes the
+  // call, so a consumer writes `ep.call(...)` without learning which transport ran.
+  const transport = transportAlias(ep.route.route.protocol)
+  if (context.hasService(transport)) {
+    req.path = ep.path()
+
+    return context.service<EntrypointTransport>(transport).handle(req, res)
+  }
+
+  // Which web client carries this call is decided by the service the route answers on — the one it
+  // names, or the one the context picks for its app type when it names none.
+  const route = ep.service()
+
+  const alias: string | undefined = typeof context.cfg.webService === 'string'
     ? context.cfg.webService
-    : (route.service != null
-      ? context.cfg.webService[route.service] ?? context.cfg.webService[DEFAULT_KEY]
-      : context.cfg.webService[DEFAULT_KEY])
+    : context.cfg.webService[route.service] ?? context.cfg.webService[DEFAULT_KEY]
 
   if (alias == null) {
     throw new SyntaxError(`Can't cast web service alias for ${ep.alias} entrypoint`)
@@ -39,15 +51,15 @@ export const apiHandler: <
 
   const service: ApiClient = context.service(alias)
 
-  req.path = ep.getPath()
+  req.path = ep.path()
 
   return service.handler(req, res as any)
 }
 
-export const apiCall: <
+export const apiInvoke: <
   T, R extends AbstractRequest = AbstractRequest
->(ref: EntrypointRef<T, R>, opts?: ClientEntrypointOptions) => EntrypointCall<T, R> =
-  (ref, opts) => (async (req, res) => {
+>(ref: EntrypointRef<T, R>, opts?: ClientEntrypointOptions) => EntrypointInvoke<T, R> =
+  (ref, opts) => (async (req) => {
     const ep = ref.ref
     if (ep == null) {
       throw new SyntaxError('Try to make API call before the entrypoint is created')
@@ -56,21 +68,24 @@ export const apiCall: <
     if (ctx == null) {
       throw new SyntaxError(`No context provided in apiCall for ${ep.alias} entrypoint`)
     }
-    await ep.route.resolve(ctx)
 
     if (req?.canceled) {
-      return
+      return { value: null, outcome: EntrypointOutcome.Ok }
     }
 
     const request: AbstractRequest = {
       alias: ep.alias,
       params: req?.params ?? {},
-      body: req?.body,
+      // JSON transports must send a body for mutation methods even when the contract has no
+      // payload.  Keeping that rule here makes every typed caller use `call({ params })`, never
+      // an SDK-specific `{ body: {} }` workaround.
+      body: req?.body ?? ([RouteMethod.POST, RouteMethod.PUT, RouteMethod.PATCH]
+        .includes(ep.route.route.method ?? RouteMethod.GET) ? {} : undefined),
       headers: req?.headers ?? {},
       query: req?.query ?? {},
       host: req?.host,
       base: req?.base,
-      path: ep.getPath(),
+      path: ep.path(),
       timeout: req?.timeout,
       signal: req?.signal,
     }
@@ -89,50 +104,59 @@ export const apiCall: <
         throw e
       }
     }
-    if (res != null) {
-      await apiHandler(ref)(request, res)
-      return
-    }
     const reply = provideResponse<unknown>()
     if (ctx == null && ep.ctx == null) {
       throw new SyntaxError(`Use entrypoint ${ep.alias} without context`)
     }
-    await apiHandler(ref)(request, reply)
-    if (reply.error != null) {
-      throw reply.error
+    try {
+      await apiHandler(ref)(request, reply)
+      if (reply.error != null) throw reply.error
+    } catch (error) {
+      if (ctx.hasService(ENTRYPOINT_FAILURE_SERVICE)) {
+        await ctx.service<EntrypointFailureService>(ENTRYPOINT_FAILURE_SERVICE)
+          .notify({ alias: ep.alias, request, error })
+      }
+      throw error
     }
 
-    return [reply.value ?? null, reply.outcome ?? EntrypointOutcome.Ok]
-  }) as EntrypointCall<any>
+    return { value: reply.value ?? null, outcome: reply.outcome ?? EntrypointOutcome.Ok }
+  }) as EntrypointInvoke<any>
 
-export const urlCall: <
+export const entrypointUrl: <
   T, R extends ClientRequest = ClientRequest
->(ref: EntrypointRef<T, R>, opts?: ClientEntrypointOptions) => EntrypointCall<T, R> = ref => async (req, res) => {
+>(ref: EntrypointRef<T, R>, req?: Partial<R>, opts?: EntrypointUrlOptions) => Promise<string> = async (ref, req, opts) => {
   const ep = ref.ref
   if (ep == null) {
     throw new SyntaxError('Try to make URL before the entrypoint is created')
   }
   const ctx = ep.ctx
   if (ctx == null) {
-    throw new SyntaxError(`No context provided in urlCall for ${ep.alias} entrypoint`)
+    throw new SyntaxError(`No context provided in entrypointUrl for ${ep.alias} entrypoint`)
   }
-  await ep.route.resolve(ctx)
 
-  const pathParams = extractParams(ep.getPath())
+  // The base is left off here: an in-service URL is addressed relative to it, and the absolute
+  // branch below has `makeUrl` prepend it.
+  const epPath = ep.path()
+  const pathParams = extractParams(epPath)
   let path = pathParams.reduce((p, param) => {
     return p.replace(`${PARAM}${param}`, `${req?.params?.[param as keyof typeof req.params]}`)
-  }, ep.getPath()) + (req?.query != null ? `?${stringify(req?.query)}` : '')
-
-  if (ep.route.route.service !== null && (
-    ctx.cfg.service !== ep.route.route.service
-    || req?.full === true)) {
+  }, epPath) + (req?.query != null ? `?${stringify(req?.query)}` : '')
+
+  // A socket address is always absolute, whoever owns the route. `new WebSocket(path)` resolves a
+  // relative value against the PAGE's origin, which in a split deployment is the web host and not
+  // the service that answers the upgrade — so the handshake goes somewhere that never speaks it
+  // and dies on a gateway timeout. Only a same-origin HTTP route benefits from staying relative.
+  const socket = ep.route.route.protocol === RouteProtocols.SOCKET
+
+  // Locality is a question about the RESOLVED service, not about what the declaration happens to
+  // name: a route that names no service belongs to the asking context, and addressing it absolutely
+  // would turn in-app navigation into a full page load.
+  if (socket || !ep.isLocal() || opts?.absolute === true) {
     const helper = makeSecurityHelper(ctx)
     path = helper.makeUrl(
-      ep.route.route, path, { host: req?.host, base: req?.base, forceUnsecure: req?.unsecure }
+      ep.address(), path, { host: req?.host, base: req?.base, forceUnsecure: req?.unsecure }
     )
   }
 
-  res?.resolve(path as any, EntrypointOutcome.Ok)
-
-  return [path as any, EntrypointOutcome.Ok]
+  return path
 }