squilla/
early alpha ★ 1
docker compose up
← back to blog
tutorials│2 min read│by Erik Kubica

Your First gRPC Extension

Walkthrough of authoring a Go extension.

This is a walkthrough of authoring a Squilla extension as a Go gRPC plugin. By the end you'll have a working extension that owns its own database table, handles an admin route, and reacts to events — mostly by reading the existing extensions and doing what they do.

The folder layout

extensions/my-extension/
  extension.json         # manifest
  cmd/plugin/main.go     # plugin entry point
  migrations/
    0001_init.sql
  admin-ui/              # optional React micro-frontend
  scripts/extension.tengo  # optional Tengo glue

The manifest

Three things matter most: slug, plugins[].binary, and capabilities. The first identifies your extension; the second tells the kernel which binary to spawn; the third declares the CoreAPI surface you intend to use. The CoreAPI guard rejects calls outside that set.

The five RPC methods

A plugin implements five gRPC methods. You'll use one or two seriously and stub the rest:

  1. Init — receive the CoreAPI handle, run startup work
  2. HandleHTTPRequest — serve admin / public routes
  3. HandleEvent — react to event bus
  4. HandleFilter — transform values in the filter chain
  5. Shutdown — flush state on deactivation

Calling back into the kernel

The SquillaHost service exposed via GRPCBroker is the kernel's surface to plugins. Roughly 35 methods across 15 domains. Typical call:

resp, err := host.NodeQuery(ctx, &coreapi.NodeQueryRequest{
    NodeType: "recipe",
    Status:   "published",
    Limit:    10,
})

Every call passes through the capability guard. If your manifest doesn't declare nodes:read, the call returns an error.

Migrations

SQL files in migrations/ run on activation in lexicographic order. Naming convention is NNNN_description.sql. The kernel records the applied set in extension_migrations; re-activation only runs new files.

Hot-deploy from a built package

Once your extension compiles, you don't need to rebuild the container. core.extension.deploy takes a base64-encoded zip, unpacks via atomic directory swap, registers the row, optionally hot-activates. 50 MB cap. Plugin binaries must already be compiled for the host's OS/arch — Squilla doesn't cross-compile.

Read the references

Three to study, in order: media-manager (full gRPC + admin UI + tables + public route), sitemap-generator (events + routes, no admin UI), email-manager (admin UI + slot system + event subscription). All three live under extensions/ in the repo.

← all posts