Specialized worker services

Begin at the generated route boundary

The Node template passes an authenticated Express router to registerRoutes. Its initial handler demonstrates request/response and access to generated provider metadata. This selected excerpt is from the generated host configuration.

registerRoutes: (router, { providerRuntime: runtimeForRoutes }) => {
  router.post('/echo', (req, res) => {
    const refs = runtimeForRoutes?.providerRefs ?? [];
    res.json({
      received: req.body ?? null,
      authoredProviderRefs: refs,
      providerRuntimeDigest: runtimeForRoutes?.sourceDigest,
    });
  });
},

The echo route does not validate a business payload or execute a provider operation. Its returned references describe the generated runtime’s declared providers. A processing route must use the appropriate provider contract when it needs an external service.

Validate before processing

The following illustrative replacement shows a small, deterministic calculation. It belongs inside the same registerRoutes callback; z is imported from zod. It demonstrates input validation and a response contract, not a built-in Wildo calculation feature.

const input = z.object({
  unitCount: z.number().int().min(0).max(10000),
  unitPriceInCents: z.number().int().min(0).max(1000000),
});

router.post('/calculate-preview', (req, res) => {
  const parsed = input.safeParse(req.body);
  if (!parsed.success) {
    res.status(400).json({ error: 'invalid_input' });
    return;
  }
  const { unitCount, unitPriceInCents } = parsed.data;
  res.json({ totalInCents: unitCount * unitPriceInCents });
});

Bounds keep the illustrated calculation within JavaScript’s safe integer range. Real pricing, taxes and currency rules belong to the application’s domain and need their own treatment.

Decide the failure and persistence contract

The HTTP host has a JSON body limit. For large input, choose a deliberate transfer mechanism rather than embedding arbitrary file contents in a request. Keep persistence and business authorization with their explicit owners.

Resolve the configured worker client

WorkerRemoteClientFactoryBackendService is registered under SAAS_SERVICE_TYPES.WorkerRemoteClientFactoryService. In backend code with the configured container, this illustrative call uses the worker map key calculationPreview and an application-authored route.

const workers = container.get<WorkerRemoteClientFactoryBackendService>(
  SAAS_SERVICE_TYPES.WorkerRemoteClientFactoryService,
);
const previewWorker = workers.client('calculationPreview');

const response = await previewWorker.post('/calculate-preview', {
  unitCount: 3,
  unitPriceInCents: 2500,
});

Import the service type and SAAS_SERVICE_TYPES from @wildo-ai/saas-backend-lib. The container, worker declaration and originating authorized business action are prerequisites, not created by this excerpt. Interpret and validate the returned response according to the remote client and your route’s contract.

The factory requires WILDO_WORKER_<NAME>_URL, using the normalized environment key for the configured worker name. It does not substitute localhost when the URL is absent. Application configuration must be initialized before dispatch so the signing key is available.

Understand what the token proves

The backend signs applicationId and workerName in an APPLICATION_WORKER_REQUEST token. The worker verifier applies the corresponding issuer, audience, signature and expiry checks using its bootstrapped trusted keys, including valid rotation keys.

The middleware exposes the verified payload as req.workerJwt. It does not, merely by accepting the signature, compare every business claim against your route’s expected application or worker identity. Add the checks required by the processing contract and verify them explicitly.

Exercise refusal as well as success

Call the route with no bearer, an invalid token and a valid signed request. Test any required application/worker claim checks separately. Then verify that an unauthorized user cannot induce the backend to make the otherwise valid service call.

Inspect the generated worker configuration

The following illustrative materialization of the Node worker template names a calculation-preview package. Its values show the template’s HTTP, resource and user settings; choose the production values for the actual workload.

import { defineWorkerConfig } from '@wildo-ai/platform-config-lib';

export default defineWorkerConfig({
  version: 1,
  name: 'calculation-preview',
  displayName: 'Calculation preview',
  description: 'Calculate preview totals for the application',
  runtime: { type: 'docker', language: 'typescript' },
  http: {
    port: 8081,
    healthPath: '/healthz',
    readyPath: '/readyz',
  },
  auth: 'wildo-jwt',
  resources: { cpu: '500m', memory: '512Mi' },
  isolation: { runAsUser: 1000, runAsGroup: 1000 },
});

The application worker bucket uses its configured key, such as calculationPreview, to point to this package path. Keep that key consistent with backend calls and provider scopes; the directory name and worker map key have different roles.

Understand startup and shutdown

The Node host reads bootstrap and HTTP environment settings, loads its generated provider runtime and initializes the worker service. Startup obtains the trusted keys used for request verification. The HTTP host exposes liveness and readiness separately; readiness changes as the service becomes ready or begins shutdown.

Custom application routes sit behind the authentication router. The host’s operational endpoints are separate from those routes. An optional metrics path only becomes useful with its configured handler; declaring a path does not manufacture processing metrics.

Verify the deployed service

The backend worker client does not poll the worker’s authored readiness path before every call. It initializes its transport and lets request failure handling address unavailable service. Choose idempotency for side effects before depending on retries.

Inspect the generated deployment and run it in the target environment. Source configuration and a successful HTTP example establish different kinds of evidence from deployed processing under load.