Events, RPC, and contract reference

Use events to notify facts, RPC to await a response, and contracts to share versioned methods. All three mechanisms operate inside the runtime: an RPC request does not itself create HTTP transport.

Receivers and returns

An event callback receives WuEvent; an RPC handler receives the payload and a second argument carrying correlation, identity, and cancellation. A contract provides a live proxy to provider methods. See communication for introductory emit, on, request, handle, provide, and consume examples.

wu.handle(channel, handler, options) preserves version, allow and replace. Inside the lifecycle, context.wu.handle also adds the app’s identity and grants; use that facade for microapp handlers.

Provider lifetime

const release = wu.eventBus.handle('catalog:lookup', ({ productId }) => {
  return { productId, available: true };
}, { version: '1.0.0' });

const product = await wu.request('catalog:lookup', { productId: 'p-42' }, {
  version: '^1.0.0', timeout: 2500,
});
console.log(product.available);
release();

A provider is released when its owner becomes unavailable. Rejecting or canceling a wait does not undo an effect already executed; the handler must cooperate with context.signal. History and replay are for observation, not repeating business operations.

wu.hasHandler / eventBus.hasHandler

Checks whether a channel has an active RPC provider.

wu.hasHandler(channel: string): boolean

• Parameters: channel: exact channel name.
• Returns: Presence boolean.
• Errors: Presence does not guarantee that your identity is authorized or the version matches.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Installs no new resources.

if (wu.hasHandler('catalog:lookup')) console.log('Proveedor disponible');

Reference: src/core/wu-event-bus.js.

wu.eventBus.history

Reads envelope history retained by the bus.

wu.eventBus.history: WuEvent[]

• Parameters: Getter without arguments; excludes history:false emissions.
• Returns: Event snapshot; default limit 100.
• Errors: Does not necessarily include the entire session history.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Installs no new resources.

console.table(wu.eventBus.history.map(event => ({ name: event.name, app: event.appName })));

Reference: src/core/wu-event-bus.js.

wu.eventBus.replay

Delivers matching historical events to the callback.

wu.eventBus.replay(pattern, callback): void

• Parameters: Pattern and WuEvent envelope callback.
• Returns: void; does not republish events on the bus.
• Errors: Does not rerun RPC handlers or recover external effects.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Leaves no subscription; use on for future events.

wu.eventBus.replay('catalog:*', event => console.log(event.data));

Reference: src/core/wu-event-bus.js.

wu.eventBus.clearHistory

Removes events from history while preserving listeners and providers.

wu.eventBus.clearHistory(pattern?): void

• Parameters: Optional pattern; omitting it empties all history.
• Returns: void.
• Errors: Does not delete projections a consumer has already saved.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Installs no new resources.

wu.eventBus.clearHistory('catalog:*');

Reference: src/core/wu-event-bus.js.

wu.eventBus.getStats

Reads bus event, subscription, and provider metrics.

wu.eventBus.getStats(): object

• Parameters: No arguments.
• Returns: Object containing counters and configuration.
• Errors: Does not measure business acceptance of events.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Installs no new resources.

console.log(wu.eventBus.getStats());

Reference: src/core/wu-event-bus.js.

wu.eventBus.matchesWildcard

Checks an event pattern without registering a subscription.

wu.eventBus.matchesWildcard(eventName, pattern): boolean

• Parameters: Event name first, pattern second.
• Returns: Boolean.
• Errors: A match does not grant permission to use that resource.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Installs no new resources.

console.log(wu.eventBus.matchesWildcard('catalog:selected', 'catalog:*'));

Reference: src/core/wu-event-bus.js.

wu.contracts.has

Queries contract presence and semver compatibility.

wu.contracts.has(name: string, range?: string): boolean

• Parameters: Name and range; * by default.
• Returns: boolean
• Errors: Check the result; it does not test external service availability.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Installs no new resources.

console.log(wu.contracts.has('formatters', '^1.0.0'));

Reference: src/core/wu-contracts.js.

wu.contracts.list

Lists active contract providers.

wu.contracts.list(): Array<{name,version,app}>

• Parameters: No arguments.
• Returns: Array<{name,version,app}>
• Errors: Check the result; it does not test external service availability.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Installs no new resources.

console.table(wu.contracts.list());

Reference: src/core/wu-contracts.js.

wu.contracts.revoke

Removes a provider by name from the host registry.

wu.contracts.revoke(name: string): boolean

• Parameters: Exact name; false when absent.
• Returns: boolean
• Errors: Check the result; it does not test external service availability.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Invalidates subsequent consumer-proxy access.

wu.contracts.revoke('formatters');

Reference: src/core/wu-contracts.js.

wu.contracts.cleanup

Revokes every provider in this contracts instance.

wu.contracts.cleanup(): void

• Parameters: No arguments.
• Returns: void
• Errors: Check the result; it does not test external service availability.
• Permissions: Host; the scoped facade does not expose global administration.
• Cleanup: Affects all registry consumers.

wu.contracts.cleanup();

Reference: src/core/wu-contracts.js.

WuEventBus.tap

Observes bus events for host instrumentation.

bus.tap(callback): () => void

• Parameters: Event callback; not a scoped application listener.
• Returns: Function for canceling the tap.
• Errors: A nonfunction value produces empty cleanup.
• Permissions: The independent instance belongs to the host creating it; does not change the WU singleton’s bus facade.
• Cleanup: Retain and execute the disposer: removeAll does not delete taps.

import { WuEventBus } from 'wu-framework';
const bus = new WuEventBus();
const stop = bus.tap(event => console.log(event));
stop();

These methods belong to an independent WuEventBus instance. The wu.eventBus facade does not expose them.

Reference: src/core/wu-event-bus.js.

WuEventBus.configure

Updates bus configuration and trims history if maxHistory changes.

bus.configure(config): void

• Parameters: maxHistory, enableReplay, enableWildcards, logEvents, strictMode, and validateOrigin.
• Returns: void.
• Errors: maxHistory must be a nonnegative safe integer; throws RangeError otherwise.
• Permissions: The independent instance belongs to the host creating it; does not change the WU singleton’s bus facade.
• Cleanup: The runtime owner manages resources and their cleanup functions.

import { WuEventBus } from 'wu-framework';
const bus = new WuEventBus();
bus.configure({ maxHistory: 100 });

These methods belong to an independent WuEventBus instance. The wu.eventBus facade does not expose them.

Reference: src/core/wu-event-bus.js.

WuEventBus.enableStrictMode

Enables strict bus controls for new operations.

bus.enableStrictMode(): void

• Parameters: No arguments.
• Returns: void.
• Errors: This call only changes configuration; subsequent operations may fail validation.
• Permissions: The independent instance belongs to the host creating it; does not change the WU singleton’s bus facade.
• Cleanup: The runtime owner manages resources and their cleanup functions.

import { WuEventBus } from 'wu-framework';
const bus = new WuEventBus();
bus.enableStrictMode();

These methods belong to an independent WuEventBus instance. The wu.eventBus facade does not expose them.

Reference: src/core/wu-event-bus.js.

WuEventBus.disableStrictMode

Disables the bus strictMode flag.

bus.disableStrictMode(): void

• Parameters: No arguments.
• Returns: void.
• Errors: The call does not return diagnostics for existing subscriptions.
• Permissions: The independent instance belongs to the host creating it; does not change the WU singleton’s bus facade.
• Cleanup: The runtime owner manages resources and their cleanup functions.

import { WuEventBus } from 'wu-framework';
const bus = new WuEventBus();
bus.disableStrictMode();

These methods belong to an independent WuEventBus instance. The wu.eventBus facade does not expose them. This is a host decision, not a way to bypass scoped-facade grants.

Reference: src/core/wu-event-bus.js.

WuEventBus.removeAll

Removes listeners and RPC handlers and rejects pending requests.

bus.removeAll(): void

• Parameters: No arguments.
• Returns: void.
• Errors: Pending requests reject with WU_RPC_BUS_CLEARED.
• Permissions: The independent instance belongs to the host creating it; does not change the WU singleton’s bus facade.
• Cleanup: Does not empty history or taps; use clearHistory and tap cancelers separately.

import { WuEventBus } from 'wu-framework';
const bus = new WuEventBus();
bus.removeAll();

These methods belong to an independent WuEventBus instance. The wu.eventBus facade does not expose them.

Reference: src/core/wu-event-bus.js.