Skip to content
AntFabric Corev1.0.0local

Server side

A plugin’s server code is a Nest module named in plugin.yaml (server: { module, class }). Core mounts it at /api/v1/plugins/<plugin id> and adds the scoped SDK services to it. Never provide those services yourself.

@Controller({ path: 'leads', version: '1' })
@ApiTags('Sales')
export class LeadsController {
constructor(private readonly sales: SalesService) {}
@Get(':id')
@Permissions('sales:read') // declared in plugin.yaml
get(
@CurrentUser() user: AuthUser,
@Param('id', ParseUUIDPipe) id: string,
): Promise<Lead> {
return this.sales.lead(user, id); // the service decides whether *this* user sees it
}
}
  • Every route needs @Permissions(...) (permissions from your manifest) or a deliberate @Public(); core refuses to start otherwise.
  • DTOs use class-validator with @ApiProperty; unknown properties are rejected.
  • After changing routes or DTOs: pnpm api:spec, and commit the result.
  • In the shared API spec and the generated client, your schemas and operation ids carry your plugin id: CreateLeadDto in af.sales is af_sales_CreateLeadDto, and SalesController.list is af_sales_SalesController_list_v1. Name your classes freely; another plugin’s names can’t collide with yours.
@Injectable()
export class SalesRepository {
constructor(private readonly db: PluginDb) {}
transaction<T>(work: (tx: NodePgDatabase) => Promise<T>): Promise<T> {
return this.db.transaction(work); // runs as role af_sales, schema sales
}
}

Write the migration first (db/migrations/000N_<what>.sql plus a journal entry), apply it with pnpm --filter backend db:migrate, then update db/schema.ts. Use Drizzle’s query builder or sql\…`` with bound parameters — never string concatenation.

Service For
PluginDb Your schema, as your role
PluginPeople get(ids), search(query), presence(ids)
PluginEvents publish(event, payload, { users, transaction, ephemeral }); on(event, handler) for events listed in events.subscribes (runs in the workers, at least once, dedupe on event.id); filterRecipients(event, fn) for your own events’ socket recipients. See docs/backend/server-events.md
PluginNotifications send({ type, recipients, context, idempotencyKey })
PluginFiles createUpload, complete, get, downloadUrl, list, delete
PluginWorkflows start({ workflow, key, input, transaction }), getStatus, requestCancel
PluginConfig, PluginSecrets Your settings and secrets
PluginAudit record({ action, target, metadata })
PluginContracts provide(name, caller => api, { actorRequired }), get<T>(name), getAll<T>(name) (extension points); caller.actor() is attached by core. Also in Activities (sdk.contracts)
PluginRateLimit hit(key, { limit, windowMs, cost }): shared by every API replica, counted per call or in units; acquire(key, { limit, leaseMs }) for concurrent slots; never a Map
PluginCache get, set(key, value, { ttlMs }), delete, getOrSet: the instance’s Redis, scoped to you, always with a TTL; never the truth
PluginJobs every(name, everyMs, run): periodic upkeep once per period across replicas, never a timer
PluginMetrics counter / gauge / histogram(name, { help, labels }), exported as af_plugin_<plugin>_<name>
@Idempotent() (decorator) a retried write with the same Idempotency-Key returns the first result; never on routes whose answer holds a secret
PluginTracer span(name, work): a span <plugin id>.<name> in the current trace
PluginContext Your plugin id, version, process, and assetPath() for runtime files you declared

Some routes need larger bodies, browsers need to send your own header, your files are big, you want pgvector: ask for it in plugin.yaml, and reviewers see it in one place.

resources:
http:
bodyLimits: [{ path: /proxy, maxBytes: 20mb }]
corsHeaders: [x-my-plugin-key]
files: { maxUploadBytes: 2gb, quotaBytes: 200gb }
postgres: { extensions: [vector] }
assets: [./server/runtime/**]

Ceilings, allow-lists and how each works: Plugin resources in the reference docs (docs/backend/plugin-resources.md). In your migrations, extension types resolve unqualified (embedding vector(768)). Files over 64 MiB upload in parts: uploadToStorage handles them, and your complete route stays the same.

Check it in the service, on every call. Return “not found” for records the person may not see. Express the rule once — Sales has one SQL condition, visibleTo(viewer), used by every query — so a list, a single read and a write cannot disagree.

Throw Nest’s exceptions (BadRequestException, ForbiddenException, NotFoundException, ServiceUnavailableException); core turns them into the error envelope with a trace id and never leaks database details.