Evolve contracts without breaking clients

This page describes WU Framework 4.0.0. Read the Framework 4.0 and CLI 1.2 migration guide before upgrading an existing project.

wu-framework/services defines schema-based contracts, validates calls and generates clients. provideService returns { dispose }; consumeService returns asynchronous methods. Inside an app use context.wu and grant rpc.provide or rpc.call for the service channels. This example uses the host runtime to focus on translation.

import { wu } from 'wu-framework';
import { schema, defineService, provideService, consumeService,
  checkServiceCompatibility } from 'wu-framework/services';

const v1 = defineService({ name: 'price', version: '1.0.0', methods: {
  quote: { input: schema.number(), output: schema.number() },
} });
const v2 = defineService({ name: 'price', version: '2.0.0', methods: {
  quote: { input: schema.object({ quantity: schema.number() }),
    output: schema.object({ total: schema.number() }) },
} });
const translators = [{ definition: v1, methods: {
  quote: { input: quantity => ({ quantity }), output: result => result.total },
} }];
const provider = provideService(wu, v2, {
  quote: ({ quantity }) => ({ total: quantity * 12 }),
}, { translators });
try {
  const oldClient = consumeService(wu, v1);
  const newClient = consumeService(wu, v2);
  console.log(await oldClient.quote(2)); // 24
  console.log(await newClient.quote({ quantity: 2 })); // { total: 24 }
  console.log(checkServiceCompatibility(v1, v2, { translators }));
} finally {
  provider.dispose();
}

What is validated

Each translator declares definition and per-method adaptations: input, output or implement to fully serve a removed method. Unchanged methods need no conversion. WU checks coverage at registration and validates each input and output against its version schema. Incomplete coverage produces WU_SERVICE_TRANSLATOR; structural checking does not prove that translation functions preserve business meaning.

checkServiceCompatibility(previous, next, { translators }) returns compatible, changes and translated. generateServiceTypes produces client declarations and sampleValue(schema) creates deterministic fixture data. See CLI contracts and tests and mocks to use the same contract in CI and development.

Versioned RPC and objects

wu.handle(channel, handler, { version, translators }) also supports direct translation. Each translators key is a served version with request and response. Context identifies version, servedVersion and translated; WU_RPC_TRANSLATION_FAILED identifies the failing stage. For shared services, wu.provide accepts translators that build an older object view; wu.consume exposes the served version through __wuVersion.