@travetto/web-rpc 6.0.0-rc.2

package/README.md

@@ -0,0 +1,31 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/web-rpc/DOC.tsx and execute "npx trv doc" to rebuild -->
+# Web RPC Support
+
+## RPC support for a Web Application
+
+**Install: @travetto/web-rpc**
+```bash
+npm install @travetto/web-rpc
+
+# or
+
+yarn add @travetto/web-rpc
+```
+
+This module allows for a highly focused scenario, of supporting RPC operations within a [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection.") application.  The module takes care of producing the appropriate handler for the RPC commands along with the ability to generate the appropriate client to be used to interact with the RPC functionality.  The generated client uses Proxy-based objects, along with [Typescript](https://typescriptlang.org) magic to create a dynamic client that does not rely on generating a lot of code.
+
+## CLI - web:rpc-client
+The library will create the RPC client in one of three flavors: fetch, fetch + node, angular.
+
+**Terminal: Command Service**
+```bash
+$ trv web:rpc-client --help
+
+Usage: web:rpc-client [options] <type:config|node|web> [output:string]
+
+Options:
+  -e, --env <string>     Application environment
+  -m, --module <module>  Module to run for
+  -h, --help             display help for command
+```

package/__index__.ts

@@ -0,0 +1,3 @@
+export * from './src/config.ts';
+export * from './src/service.ts';
+export * from './src/controller.ts';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@travetto/web-rpc",
+  "version": "6.0.0-rc.2",
+  "description": "RPC support for a Web Application",
+  "keywords": [
+    "web",
+    "rpc",
+    "client",
+    "travetto",
+    "typescript"
+  ],
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src",
+    "support"
+  ],
+  "main": "__index__.ts",
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/web-rpc"
+  },
+  "dependencies": {
+    "@travetto/config": "^6.0.0-rc.2",
+    "@travetto/schema": "^6.0.0-rc.2",
+    "@travetto/web": "^6.0.0-rc.2"
+  },
+  "travetto": {
+    "displayName": "Web RPC Support"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,14 @@
+import { Config } from '@travetto/config';
+
+export type WebRpcClient = {
+  type: 'node' | 'web';
+  output: string;
+};
+
+/**
+ * Web body parse configuration
+ */
+@Config('web.rpc')
+export class WebRpcConfig {
+  clients: WebRpcClient[] = [];
+}

package/src/controller.ts

@@ -0,0 +1,54 @@
+import { Inject } from '@travetto/di';
+import { Any, AppError, Util } from '@travetto/runtime';
+import {
+  HeaderParam, Controller, Undocumented, ExcludeInterceptors, ControllerRegistry,
+  WebAsyncContext, Body, EndpointUtil, BodyParseInterceptor, Post, WebCommonUtil,
+  RespondInterceptor
+} from '@travetto/web';
+
+@Controller('/rpc')
+@ExcludeInterceptors(val => !(val instanceof BodyParseInterceptor || val instanceof RespondInterceptor || val.category === 'global'))
+@Undocumented()
+export class WebRpController {
+
+  @Inject()
+  ctx: WebAsyncContext;
+
+  /**
+   * RPC main entrypoint
+   */
+  @Post('/:target')
+  async onRequest(target: string, @HeaderParam('X-TRV-RPC-INPUTS') paramInput?: string, @Body() body?: Any): Promise<unknown> {
+    const endpoint = ControllerRegistry.getEndpointById(target);
+
+    if (!endpoint) {
+      throw new AppError('Unknown endpoint', { category: 'notfound' });
+    }
+
+    const bodyParamIdx = endpoint.params.findIndex((x) => x.location === 'body');
+
+    const { request } = this.ctx;
+
+    let params: unknown[];
+
+    // Allow request to read inputs from header
+    if (paramInput) {
+      params = Util.decodeSafeJSON(paramInput)!;
+    } else if (Array.isArray(body)) { // Params passed via body
+      params = body;
+      if (bodyParamIdx >= 0) { // Re-assign body
+        request.body = params[bodyParamIdx];
+      }
+    } else if (body) {
+      throw new AppError('Invalid parameters, must be an array', { category: 'data' });
+    } else {
+      params = [];
+    }
+
+    const final = endpoint.params.map((x, i) => (x.location === 'body' && paramInput) ? EndpointUtil.MissingParamSymbol : params[i]);
+    WebCommonUtil.setRequestParams(request, final);
+
+    // Dispatch
+    return await endpoint.filter!({ request: this.ctx.request });
+  }
+}

package/src/service.ts

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { Inject, Injectable } from '@travetto/di';
+import { ControllerRegistry } from '@travetto/web';
+import { Runtime, RuntimeIndex } from '@travetto/runtime';
+import { ManifestModuleUtil } from '@travetto/manifest';
+
+import { clientFactory } from '../support/client/rpc.ts';
+import { WebRpcClient, WebRpcConfig } from './config.ts';
+
+@Injectable({ autoCreate: !Runtime.production })
+export class WebRpcClientGeneratorService {
+
+  @Inject()
+  config: WebRpcConfig;
+
+  async postConstruct(): Promise<void> {
+    this.render();
+
+    if (!this.config.clients.length || !Runtime.dynamic) {
+      return;
+    }
+    ControllerRegistry.on(() => this.render());
+  }
+
+  async #getClasses(relativeTo: string): Promise<{ name: string, import: string }[]> {
+    return ControllerRegistry.getClasses()
+      .filter(x => {
+        const entry = RuntimeIndex.getEntry(Runtime.getSourceFile(x));
+        return entry && entry.role === 'std';
+      })
+      .map(x => {
+        const imp = ManifestModuleUtil.withOutputExtension(Runtime.getImport(x));
+        const base = Runtime.workspaceRelative(RuntimeIndex.manifest.build.typesFolder);
+        return {
+          name: x.name,
+          import: path.relative(relativeTo, `${base}/node_modules/${imp}`)
+        };
+      });
+  }
+
+  async renderProvider(config: WebRpcClient): Promise<void> {
+    await fs.mkdir(config.output, { recursive: true });
+
+    const classes = await this.#getClasses(config.output);
+
+    const clientSourceFile = RuntimeIndex.getFromImport('@travetto/web-rpc/support/client/rpc.ts')!.sourceFile;
+    const clientOutputFile = path.resolve(config.output, path.basename(clientSourceFile));
+    const clientSourceContents = await fs.readFile(clientSourceFile, 'utf8');
+
+    const flavorSourceFile = RuntimeIndex.getFromImport(`@travetto/web-rpc/support/client/rpc-${config.type}.ts`)!.sourceFile;
+    const flavorOutputFile = path.resolve(config.output, path.basename(flavorSourceFile));
+    const flavorSourceContents = (await fs.readFile(flavorSourceFile, 'utf8').catch(() => ''))
+      .replaceAll(/^\s*\/\/\s*@ts-ignore[^\n]*\n/gsm, '')
+      .replaceAll(/^\/\/\s*#UNCOMMENT (.*)/gm, (_, v) => v);
+
+    const factoryOutputFile = path.resolve(config.output, 'factory.ts');
+    const factorySourceContents = [
+      `import { ${clientFactory.name} } from './rpc.ts';`,
+      ...classes.map((n) => `import type { ${n.name} } from '${n.import}';`),
+      '',
+      `export const factory = ${clientFactory.name}<{`,
+      ...classes.map(x => `  ${x.name}: ${x.name};`),
+      '}>();',
+    ].join('\n');
+
+    await fs.writeFile(clientOutputFile, clientSourceContents, 'utf8');
+    await fs.writeFile(factoryOutputFile, factorySourceContents, 'utf8');
+
+    if (flavorSourceContents) {
+      await fs.writeFile(flavorOutputFile, flavorSourceContents, 'utf8');
+    }
+  }
+
+  async render(): Promise<void> {
+    for (const config of this.config.clients) {
+      this.renderProvider(config);
+    }
+  }
+}

package/support/cli.web_rpc-client.ts

@@ -0,0 +1,45 @@
+import path from 'node:path';
+
+import { Env } from '@travetto/runtime';
+import { CliCommand, CliCommandShape, CliValidationResultError } from '@travetto/cli';
+import { DependencyRegistry } from '@travetto/di';
+import { RootRegistry } from '@travetto/registry';
+import { Ignore } from '@travetto/schema';
+
+import type { WebRpcClient } from '../src/config.ts';
+import { WebRpcClientGeneratorService } from '../src/service.ts';
+
+/**
+ * Generate the web-rpc client
+ */
+@CliCommand({ with: { env: true, module: true } })
+export class CliWebRpcCommand implements CliCommandShape {
+
+  @Ignore()
+  module: string;
+
+  preMain(): void {
+    Env.DEBUG.set(false);
+    Env.TRV_DYNAMIC.set(false);
+  }
+
+  get #service(): Promise<WebRpcClientGeneratorService> {
+    return RootRegistry.init().then(() => DependencyRegistry.getInstance(WebRpcClientGeneratorService));
+  }
+
+  async main(type: WebRpcClient['type'] | 'config', output?: string): Promise<void> {
+    if (type === 'config') {
+      const svc = await this.#service;
+      await svc.render();
+    } else {
+      if (!output) {
+        throw new CliValidationResultError(this, [
+          { message: 'output is required when type is not `config`', source: 'arg' }
+        ]);
+      }
+      const svc = await this.#service;
+      output = path.resolve(output);
+      return svc.renderProvider({ type, output });
+    }
+  }
+}

package/support/client/rpc-node.ts

@@ -0,0 +1,13 @@
+import { consumeError } from './rpc.ts';
+
+export async function toNodeError(payload: unknown): Promise<Error> {
+  try {
+    let res = undefined;
+    const { AppError } = await import('@travetto/runtime');
+    res = AppError.fromJSON(payload);
+    if (res) {
+      return res;
+    }
+  } catch { }
+  return consumeError(payload);
+}

package/support/client/rpc.ts

@@ -0,0 +1,272 @@
+type MethodKeys<C extends {}> = {
+  [METHOD in keyof C]: C[METHOD] extends Function ? METHOD : never
+}[keyof C];
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type PromiseFn = (...args: any) => Promise<unknown>;
+type PromiseRes<V extends PromiseFn> = Awaited<ReturnType<V>>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const isBlobMap = (x: any): x is Record<string, Blob> => x && typeof x === 'object' && x[Object.keys(x)[0]] instanceof Blob;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const isBlobLike = (x: any): x is Record<string, Blob> | Blob => x instanceof Blob || isBlobMap(x);
+
+export type PreRequestHandler = (item: RequestInit) => Promise<RequestInit | undefined | void>;
+export type PostResponseHandler = (item: Response) => Promise<Response | undefined | void>;
+
+export type RpcRequest = {
+  core?: Partial<RequestInit> & {
+    timeout?: number;
+    retriesOnConnectFailure?: number;
+    path?: string;
+  };
+  url: URL | string;
+  consumeJSON?: <T>(text?: unknown) => (T | Promise<T>);
+  consumeError?: (item: unknown) => (Error | Promise<Error>);
+  preRequestHandlers?: PreRequestHandler[];
+  postResponseHandlers?: PostResponseHandler[];
+};
+
+export type RpcClient<T extends Record<string, {}>, E extends Record<string, Function> = {}> = {
+  [C in keyof T]: Pick<T[C], MethodKeys<T[C]>> & Record<MethodKeys<T[C]>, E>
+};
+
+export type RpcClientFactory<T extends Record<string, {}>> =
+  <R extends Record<string, Function>>(
+    baseOpts: RpcRequest,
+    decorate?: (opts: RpcRequest) => R
+  ) => RpcClient<T, R>;
+
+function isResponse(v: unknown): v is Response {
+  return !!v && typeof v === 'object' && 'status' in v && !!v.status && 'headers' in v && !!v.headers;
+}
+
+function isPlainObject(obj: unknown): obj is Record<string, unknown> {
+  return typeof obj === 'object' // separate from primitives
+    && obj !== undefined
+    && obj !== null         // is obvious
+    && obj.constructor === Object // separate instances (Array, DOM, ...)
+    && Object.prototype.toString.call(obj) === '[object Object]'; // separate build-in like Math
+}
+
+function registerTimeout<T extends (number | string | { unref(): unknown })>(
+  controller: AbortController,
+  timeout: number,
+  start: (fn: (...args: unknown[]) => unknown, delay: number) => T,
+  stop: (val: T) => void
+): void {
+  const timer = start(() => controller.abort(), timeout);
+  if (!(typeof timer === 'number' || typeof timer === 'string')) {
+    timer.unref();
+  }
+  controller.signal.onabort = (): void => { timer && stop(timer); };
+}
+
+function buildRequest<T extends RequestInit>(base: T, controller: string, endpoint: string): T {
+  return {
+    ...base,
+    method: 'POST',
+    path: `${controller}:${endpoint}`,
+    headers: {
+      ...base.headers,
+      'Content-Type': 'application/json',
+    }
+  };
+}
+
+export function getBody(inputs: unknown[]): { body: FormData | string, headers: Record<string, string> } {
+  // If we do not have a blob, simple output
+  if (!inputs.some(isBlobLike)) {
+    return {
+      body: JSON.stringify(inputs),
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    };
+  }
+
+  const plainInputs = inputs.map(x => isBlobLike(x) ? null : x);
+  const form = new FormData();
+
+  for (const inp of inputs.filter(isBlobLike)) {
+    if (inp instanceof Blob) {
+      form.append('file', inp, (inp instanceof File) ? inp.name : undefined);
+    } else {
+      for (const [name, blob] of Object.entries(inp)) {
+        form.append(name, blob, (blob instanceof File) ? blob.name : undefined);
+      }
+    }
+  }
+
+  return {
+    body: form,
+    headers: {
+      'X-TRV-RPC-INPUTS': btoa(encodeURIComponent(JSON.stringify(plainInputs)))
+    }
+  };
+}
+
+export function consumeJSON<T>(text: string | unknown): T {
+  if (typeof text !== 'string') {
+    return consumeJSON(JSON.stringify(text));
+  } else if (text === null || text === undefined || text === '') {
+    return undefined!;
+  }
+  try {
+    return JSON.parse(text, (key, value): unknown => {
+      if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[.]\d{3}Z/.test(value)) {
+        return new Date(value);
+      } else {
+        return value;
+      }
+    });
+  } catch (err) {
+    throw new Error(`Unable to parse response: ${text}, Unknown error: ${err}`);
+  }
+}
+
+export async function consumeError(err: unknown): Promise<Error> {
+  if (err instanceof Error) {
+    return err;
+  } else if (isResponse(err)) {
+    const out = new Error(err.statusText);
+    Object.assign(out, { status: err.status });
+    return consumeError(out);
+  } else if (isPlainObject(err)) {
+    const out = new Error();
+    Object.assign(out, err);
+    return consumeError(out);
+  } else {
+    return new Error('Unknown error');
+  }
+}
+
+export async function invokeFetch<T>(request: RpcRequest, ...params: unknown[]): Promise<T> {
+  let core = request.core!;
+
+  try {
+    const { body, headers } = getBody(params);
+    core.body = body;
+    core.headers = {
+      ...core.headers ?? {},
+      ...headers
+    };
+
+    for (const fn of request.preRequestHandlers ?? []) {
+      const computed = await fn(core);
+      if (computed) {
+        core = computed;
+      }
+    }
+
+    const signals = [];
+    if (core.signal) {
+      signals.push(core.signal);
+    }
+
+    if (core.timeout) {
+      const controller = new AbortController();
+      // Node/Browser handling of timeout registration
+      registerTimeout(controller, core.timeout, setTimeout, clearTimeout);
+      signals.push(controller.signal);
+    }
+
+    if (signals.length) {
+      core.signal = AbortSignal.any(signals);
+    }
+
+    let resolved: Response | undefined;
+    for (let i = 0; i <= (core.retriesOnConnectFailure ?? 0); i += 1) {
+      try {
+        const url = typeof request.url === 'string' ? new URL(request.url) : request.url;
+        if (request.core?.path) {
+          url.pathname = `${url.pathname}/${request.core.path}`.replaceAll('//', '/');
+        }
+        resolved = await fetch(url, core);
+        break;
+      } catch (err) {
+        if (i < (core.retriesOnConnectFailure ?? 0)) {
+          await new Promise(r => setTimeout(r, 1000)); // Wait 1s
+          continue;
+        } else {
+          throw err;
+        }
+      }
+    }
+
+    if (!resolved) {
+      throw new Error('Unable to connect');
+    }
+
+    for (const fn of request.postResponseHandlers ?? []) {
+      const computed = await fn(resolved);
+      if (computed) {
+        resolved = computed;
+      }
+    }
+
+    const contentType = resolved.headers.get('Content-Type')?.split(';')[0];
+
+    if (resolved.ok) {
+      const text = await resolved.text();
+      if (contentType === 'application/json') {
+        return await request.consumeJSON!<T>(text);
+      } else if (contentType === 'text/plain') {
+        return await request.consumeJSON!<T>(text);
+      } else {
+        throw new Error(`Unknown content type: ${contentType}`);
+      }
+    } else {
+      let responseObject;
+      if (contentType === 'application/json') {
+        const text = await resolved.text();
+        responseObject = await request.consumeJSON!(text);
+      } else {
+        responseObject = resolved;
+      }
+      throw responseObject;
+    }
+  } catch (err) {
+    throw await request.consumeError!(err);
+  }
+}
+
+export function clientFactory<T extends Record<string, {}>>(): RpcClientFactory<T> {
+  // @ts-ignore
+  return function (opts, decorate) {
+    const client: RpcRequest = {
+      consumeJSON,
+      consumeError,
+      ...opts,
+      core: { timeout: 0, credentials: 'include', mode: 'cors', ...opts.core },
+    };
+    const cache: Record<string, unknown> = {};
+    // @ts-ignore
+    return new Proxy({}, {
+      get: (_, controller: string) =>
+        cache[controller] ??= new Proxy({}, {
+          get: (__, endpoint: string): unknown => {
+            const final: RpcRequest = {
+              ...client,
+              core: buildRequest(client.core!, controller, endpoint)
+            };
+            return cache[`${controller}/${endpoint}`] ??= Object.defineProperties(
+              invokeFetch.bind(null, final),
+              Object.fromEntries(
+                Object.entries(decorate?.(final) ?? {}).map(([k, v]) => [k, { value: v }])
+              )
+            );
+          }
+        })
+    });
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function withConfigFactoryDecorator(opts: RpcRequest) {
+  return {
+    withConfig<V extends PromiseFn>(this: V, extra: Partial<RpcRequest['core']>, ...params: Parameters<V>): Promise<PromiseRes<V>> {
+      return invokeFetch({ ...opts, core: { ...opts.core, ...extra } }, ...params);
+    }
+  };
+}