# Events, RPC, and contract reference

History, queries, versioned providers, and limits on application communication.

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.

<span id="receptores-y-retorno"></span>

<span class="section-anchor" id="section-1"></span>

## 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](/docs/framework/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.

<span id="vida-del-proveedor"></span>

<span class="section-anchor" id="section-2"></span>

## Provider lifetime

```js
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.

<span class="section-anchor" id="section-3"></span>

## 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.

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

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

<span class="section-anchor" id="section-4"></span>

## 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.

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

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

<span class="section-anchor" id="section-5"></span>

## 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.

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

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

<span class="section-anchor" id="section-6"></span>

## 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.

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

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

<span class="section-anchor" id="section-7"></span>

## 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.

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

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

<span class="section-anchor" id="section-8"></span>

## 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.

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

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

<span class="section-anchor" id="section-9"></span>

## 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.

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

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

<span class="section-anchor" id="section-10"></span>

## 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.

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

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

<span class="section-anchor" id="section-11"></span>

## 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.

```js
wu.contracts.revoke('formatters');
```

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

<span class="section-anchor" id="section-12"></span>

## 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.

```js
wu.contracts.cleanup();
```

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

<span class="section-anchor" id="section-13"></span>

## 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.

```js
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`.

<span class="section-anchor" id="section-14"></span>

## 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.

```js
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`.

<span class="section-anchor" id="section-15"></span>

## 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.

```js
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`.

<span class="section-anchor" id="section-16"></span>

## 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.

```js
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`.

<span class="section-anchor" id="section-17"></span>

## 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.

```js
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`.