WebHare RPC client

Webhare RPC services are built to integrate into WebHare front- and backend apps

@webhare/rpc library exposes a rpc function which takes a service name (which is resolved to a URL using WebHare's service naming conventions) or the full URL to the typed RPC service to invoke. You can then directly invoke any API offered by the service direcly on the returned client object. Internally the service is implemented as a Proxy which will construct a function to call the named remote API for any property requested.

The client can be configured using the options parameter to rpc or per call by using withOptions.

To execute RPC calls, construct the service using the type of the API you will be invoking. This call is automatically typesafe:

import { rpc } from "@webhare/rpc";
const result = await rpc("mymodule:myapi").myfunction(param1, param2);

If you can't use the autogenerated types you can explicitly specify the shape of the API you'e calling as a type parameter to rpc:

import { rpc } from "@webhare/rpc";
import type { testAPI } from '@mod-webhare_testsuite/js/rpcservice';

const client = rpc<typeof testAPI>("mymodule:myapi");
const result = await client.myfunction(param1, param2);

You can pass options such as debug and signal (for abort) as the options parameter to rpc, but you can also change these for just one call:

const client = rpc("mymodule:myapi", {timeout: 500});
let result2 = await client.withOptions({debug: true}).myfunction(param1, param2);

The actual service name (mymodule:myapi) is determinated by the backend developer. See https://www.webhare.dev/manuals/typescript/jsonrpc/ for more information on setting services.

Using rpc-client outside WebHare

Install: npm install @webhare/rpc

And use it. JavaScript:

const { rpc } = require ("@webhare/rpc");

async function main() {
  const client = rpc("https://your.webhare.dev/.wh/rpc/webhare_testsuite/testapi/");
  console.log(await client.echo(1, 2, 3));
}
main();

or TypeScript:

import { rpc } from "@webhare/rpc";

const client = rpc<any>("https://webhare.moe.sf.webhare.dev/.wh/rpc/webhare_testsuite/testapi/");
console.log(await client.echo(1, 2, 3));

(But ideally you would then also supply a type definition for rpc to get full TypeScript support)

Temporal types

@webhare/rpc supports the temporal types implemented by @webhare/std's typed stringify such as Temporal.Instant but does not include a polyfill for Temporal itself. RPC will fail if they receive a Temporal in a response but can't find the Temporal global object.

We recommend importing @webhare/deps/temporal-polyfill when building webpages inside WebHare. Outside WebHare we recommend importing temporal-polyfill/global

Error tracing and debugging

@webhare/rpc can generate cross-server error traces but requires the origin server to return its part of the stack trace. Generating a cross-error trace depends on the request or the server having the etr debug flag set (Error TRace). This can be set using either a wh-debug cookie (use WebHare's debug settings) or by enabling the global etr flag for a WebHare installation (wh debug enable etr).

Enabling the etr debug flag globally returns error traces to ALL users and may lead to sensitive information being exposed. Use with caution.

The etr flag cannot be enabled by simply adding ?wh-debug=etr to the request URL as the etr flag requires a signed cookie/variable

The @webhare/rpc client also supports logging its request/response by setting the wrq debug flag. This flag should be set in either:

• the debugFlags variable (as exposed by @webhare/env)
• wh-debug cookies or URL variables (this does not require a signed variable)
• the WEBHARE_DEBUG environent variable (eg WEBHARE_DEBUG=wrq wh run ...)

Keep in mind that etr is a server-side flag and wrq is a client-side flag. You cannot enable etr from the client.

Publication source

The source code for @webhare/rpc is part of the WebHare Platform