Skip to content
AntFabric Corev1.0.0local

Contracts between plugins

A plugin that needs another plugin to do something — Sales opening a private channel in Chat — calls it through a contract: a typed interface the provider declares and implements, looked up in core’s contract registry at the moment of use.

Option Why not
Import the other plugin’s code Lint forbids it: only another plugin’s contracts package (types) may be imported
Write the other plugin’s tables The database forbids it: each plugin’s role sees only its own schema
Call its HTTP API as the user Untyped, needs the user’s token passed through, and nothing keeps the caller to its own records
  1. Declare. The provider’s manifest lists contracts.provides: [{ name: chat, version: 1.1.0 }]; the caller’s lists contracts.requires: [{ name: chat, version: ^1.1.0, optional: true }] — a range, or a bare version meaning the same major. optional: true means the caller works without it; extension: true (on both sides) makes it an extension point with many providers.
  2. Describe. The interface lives in the provider’s contracts package: ChatApi in @antfabric-contracts/chat. Types only, no code.
  3. Provide. At start-up the provider registers a factory:
    onModuleInit() {
    this.contracts.provide<ChatApi>('chat', (caller) => this.forCaller(caller), {
    actorRequired: ['recordChannel', 'post'], // refused by core when nobody is acting
    });
    }
  4. Use. The caller asks when it needs it:
    const chat = this.contracts.get<ChatApi>('chat');
    if (!chat) throw new ServiceUnavailableException('Chat is not installed');
    await chat.recordChannel(user, { recordKey: `lead:${id}`, name, memberIds });
    get returns null when an optional contract’s provider is not installed. The caller must degrade: Sales hides “Discuss in Chat” and skips the “deal won” post. For an extension point, getAll<T>(name) returns every provider ({ pluginId, version, api }), sorted by plugin id.
  • A plugin can provide only contracts in its provides, and use only those in its requires. Anything else throws at the call.
  • One provider per contract, unless it is an extension point. Codegen refuses two providers, a provider version a caller cannot use, and a required (not optional) contract nobody provides.
  • The factory learns who calls (caller.pluginId), so the provider keeps each caller to its own records. Chat prefixes record-channel keys with the caller’s id.
  • Core attaches the person the call is for: await caller.actor() is the signed-in person during a request, the workflow’s user in an Activity or event handler, or null. Don’t trust an actor the caller passes in. Chat compares it with caller.actor() and refuses a mismatch. Methods in actorRequired are refused by core (403) when there is no actor.
  • No route guard runs, so the provider checks that person’s permissions itself.
  • The provider’s code runs in the provider’s module, with the provider’s database role.
  • Contracts work in the workers too: plugin modules boot there, so Activities call them through sdk.contracts.
  • Contracts stay in-process: an AsyncIterable result or an AbortSignal argument may cross them.
  • Never call a contract inside your own database transaction — the provider has its own.
  • Contracts change additively within a major version; a breaking change is a new major, offered side by side until callers move.
Piece Path
SDK interface libs/sdk-server/src/plugin-contracts.ts (PluginContracts)
Registry apps/backend/src/plugins/contract-registry.ts
Manifest checks libs/plugin-manifest (checkInstalled, contractSatisfies)
Example provider plugins/example/server/example.contract.ts; a real one: Chat’s server/chat.contract.ts (plugins/chat)
Example caller Sales’s server/sales.service.ts (plugins/sales); core’s test caller in apps/backend/test/contracts.e2e-spec.ts