Cufflink

Deploy CRUD microservices in seconds. Define your data model in Rust, run cufflink deploy, and get a full REST API with PostgreSQL persistence, automatic schema migrations, NATS events, and multi-tenant isolation.

Architecture

┌─────────────┐     ┌──────────────┐     ┌───────────┐
│  Cufflink   │────>│   Platform   │────>│ PostgreSQL│
│  CLI        │     │   (Axum)     │     │           │
└─────────────┘     └──────┬───────┘     └───────────┘
                           │
┌─────────────┐     ┌──────┴───────┐     ┌───────────┐
│  Keycloak   │<────│  Dynamic     │────>│   NATS    │
│  (JWT)      │     │  CRUD Router │     │ JetStream │
└─────────────┘     └──────────────┘     └───────────┘

• SDK — #[derive(Table)] and service! proc macros generate a JSON manifest from Rust structs
• CLI — cufflink deploy builds the project, captures the manifest and POSTs it to the platform
• Platform — applies schema migrations, registers CRUD routes, runs WASM handlers, publishes events
• WASM worker — runs offloaded WASM handlers and long-running jobs over NATS, scales independently
• web-runner — serves deployed Next.js apps (mode = "web" services) at {service}--{tenant}.{base domain}
• ext-runner — runs native services (mode = "native"), which provide extensions to a tenant's WASM services

Quick Start

Prerequisites

• Rust — rust-toolchain.toml pins 1.93.1; rustup installs it on the first cargo command
• Docker + Docker Compose
• The wasm32-unknown-unknown target, only if you build WASM services: rustup target add wasm32-unknown-unknown

1. Start the platform

docker compose up -d
curl localhost:8080/health
# cufflink-platform ok

This starts PostgreSQL, NATS (JetStream), Keycloak (with two realms imported from infra/keycloak/), Redis, RustFS (S3-compatible object storage, bucket cufflink), the platform, the WASM worker, web-runner, ext-runner, and a monitoring stack (OTel collector, Tempo, Loki, Prometheus, Grafana). Two one-shot containers run once: bucket-init creates the bucket and tenant-init registers the dev tenant.

Everything you need to log in is pre-provisioned:

The kingsleyh/cufflink-* images are published for linux/amd64 only; compose pins platform: linux/amd64, so Docker Desktop on Apple Silicon runs them under emulation (slower startup, but it works).

2. Install the CLI

cargo install cufflink-cli          # from crates.io
# or, from this checkout:
cargo build -p cufflink-cli         # binary at target/debug/cufflink

The binary is cufflink. (cargo run -p cufflink is the SDK library crate, not the CLI.)

3. Log in

Every CLI command (except cufflink tenants ...) reads a Cufflink.toml from the project directory. Both examples ship one pointing at the compose stack:

[service]
default_env = "local"

[environments.local]
api_url = "http://localhost:8080"
tenant = "acme"
keycloak_url = "http://localhost:8180"
keycloak_realm = "acme"

cd examples/todo-service
cufflink login

Environment: local
Authenticating with Cufflink...
  Open this URL in your browser:
  http://localhost:8180/realms/acme/device?user_code=XXXX-XXXX

  Enter code: XXXX-XXXX

Waiting for authentication...

This is the OAuth device-code flow: the CLI does not open a browser. Open the URL, sign in as dev / dev, and the CLI exchanges the Keycloak token for a platform API key (ck_...) which it stores in ~/.config/cufflink/credentials.json.

Non-interactive alternative: set CUFFLINK_API_KEY in the environment. It takes precedence over stored credentials.

4. Deploy

cufflink deploy

Environment: local
Building service...
Deploying todo-service (mode: crud)...
Deployed todo-service v2
  Schema changes: 1
  Deployment ID:  "98e338c3-..."
  Tenant:         "acme"
  Commit:         f1af9c6...

5. Use the API

The todos table in this example is auth_required with owner_field = "user_id", so every request needs an API key and every row is scoped to its owner. Take the key from ~/.config/cufflink/credentials.json (or use the one in CUFFLINK_API_KEY):

export KEY=ck_...
BASE=http://localhost:8080/svc/acme/todo-service/todos

# Create — user_id is set from the caller, not the body
curl -X POST $BASE -H "Authorization: ApiKey $KEY" -H "Content-Type: application/json" \
  -d '{"title": "Buy groceries", "completed": false}'

# List (sorting, pagination, search, filter)
curl -H "Authorization: ApiKey $KEY" "$BASE?sort=-created_at&per_page=10"
curl -H "Authorization: ApiKey $KEY" "$BASE?search=groceries"
curl -H "Authorization: ApiKey $KEY" --get $BASE \
  --data-urlencode 'filter=[{"n":"completed","f":"=","v":"false"}]'

# Get / update / delete by ID
curl -H "Authorization: ApiKey $KEY" $BASE/{id}
curl -X PUT $BASE/{id} -H "Authorization: ApiKey $KEY" -H "Content-Type: application/json" \
  -d '{"completed": true}'
curl -X DELETE -H "Authorization: ApiKey $KEY" $BASE/{id}

List responses look like this:

{
  "results": [
    {"id": "…", "user_id": "platform-acme", "title": "Buy groceries", "completed": false,
     "created_at": "…", "updated_at": "…"}
  ],
  "pagination": {"current_page": 1, "per_page": 10, "total_pages": 1, "total_records": 1}
}

Without the header you get 401 {"error": "..."}; a GET after DELETE returns 404. For a service with no auth at all, deploy examples/blog-service and drop the header.

The service you just deployed

examples/todo-service/src/main.rs:

use cufflink::prelude::*;

#[derive(Table, Serialize, Deserialize, Clone)]
#[table(name = "todos", auth_required, owner_field = "user_id")]
pub struct Todo {
    #[key]
    pub id: Uuid,
    pub user_id: String,
    pub title: String,
    pub completed: bool,
    #[timestamp]
    pub created_at: DateTime<Utc>,
    #[timestamp]
    pub updated_at: DateTime<Utc>,
}

cufflink::service! {
    name: "todo-service",
    tables: [Todo],
}

• auth_required — anonymous requests to this table get 401.
• owner_field = "user_id" — on create the column is filled with the caller's subject, and reads, updates and deletes only see that caller's rows.

SDK Reference

#[table(...)] attributes

Field attributes

Table-level hooks call WASM handlers around CRUD operations:

#[hooks(before_create = "validate_item", after_create = "audit_item_created", before_delete = "check_owner_can_delete")]

All six are available: before_create, after_create, before_update, after_update, before_delete, after_delete.

Supported types

service! keys

cufflink::service! {
    name: "orders",
    mode: wasm,                       // crud (default) | wasm | container
    tables: [Order, LineItem],
    authorization: [
        areas: [("orders", ["create", "view", "edit", "delete"])],
        default_roles: [
            ("admin", "Full access", ["orders:*"]),
            ("viewer", "Read-only", ["orders:view"]),
        ],
    ],
    custom_routes: [
        // (method, path, handler, posture[, job(...)])
        ("GET",  "/health",   "health",   public("unauthenticated probe")),
        ("POST", "/checkout", "checkout", auth),
        ("POST", "/refund",   "refund",   perm("orders", "edit")),
        ("GET",  "/mine",     "mine",     owner("user_id")),
        ("POST", "/export",   "export",   auth, job(timeout = 900, max_attempts = 3)),
    ],
    subscriptions: [("orders.>", "on_order_event", wasm)],   // wasm | webhook | delete_cascade | update_field
    on_migrate: "backfill",
    publishes: ["orders.created", "orders.refunded"],
}

Every custom route should declare exactly one posture — public("reason"), auth, perm("area", "op") or owner("field"). A route without one runs unenforced and the platform logs a warning; set CUFFLINK_ENFORCE_ROUTE_POSTURE=true on the platform to reject such deploys. job(...) turns the route into a long-running job (defaults: 600 s timeout, 3 attempts). Web apps (mode = "web") are declared in Cufflink.toml, not in service! — see docs/setup.md.

See docs/wasm-guide.md for handlers, docs/authorization.md for RBAC, and docs/guides.md for the rest.

CLI Reference

All commands accept --env/-e <name> to pick an [environments.<name>] block from Cufflink.toml (default: [service].default_env).

API Endpoints

Dynamic CRUD routes

Query parameters (list endpoints)

Filter operators: =, !=, >, <, >=, <=, LIKE, ILIKE, IN, IS NULL, IS NOT NULL (case-insensitive; eq, neq, gt, gte, lt, lte also work). Conditions on the same column are OR'd together, conditions on different columns are AND'd — so a range on one column (>= a AND <= b) is not expressible with filter. Only the object form is supported; array-of-arrays is not.

Cursor pagination: an empty ?cursor= starts from the first row (ordered by primary key ascending) and the response is {"results": [...], "next_cursor": "<base64>", "has_more": true}; pass next_cursor back to fetch the next page. Offset mode (page/per_page) never returns next_cursor.

Management API

All routes are relative to the platform (http://localhost:8080). /health returns plain text, /ready returns JSON.

The full list (webhooks, files, config, logs, SQL, RBAC, web apps) is in docs/setup.md.

Project Structure

cufflink/
├── platform/          # Axum platform server (deployer, CRUD router, WASM runtime)
├── worker/            # WASM worker process (NATS-driven, scales independently)
├── web-runner/        # Serves deployed Next.js "web" mode apps
├── ext-runner/        # Runs native services and relays their extension calls
├── supervisor/        # Child-process supervision the runners share
├── cli/               # The `cufflink` binary (crate: cufflink-cli)
├── sdk/               # User-facing SDK crate (crate: cufflink)
├── sdk-macros/        # #[derive(Table)] and service! proc macros
├── cufflink-fn/       # WASM handler SDK (handler!, Request, Response, host calls)
├── native/            # Native extension SDK (crate: cufflink-native)
├── types/             # Shared types (ServiceManifest, ColumnType, ...)
├── db/                # Shared PostgreSQL pool helpers
├── storage/           # Object storage abstraction (S3-compatible or GCS)
├── examples/
│   ├── todo-service/  # Single table with auth_required + owner_field
│   ├── blog-service/  # Multi-table example with foreign keys, no auth
│   └── ext-echo/      # Native service whose extensions echo, fail and sleep
├── infra/             # Keycloak realm imports, compose bootstrap, monitoring config
├── docs/
├── docker-compose.yml
├── Dockerfile.platform
├── Dockerfile.worker
├── Dockerfile.web-runner
└── Dockerfile.ext-runner

Development

Run the infrastructure from compose and the platform natively:

docker compose up -d
docker compose stop platform

DATABASE_URL=postgres://cufflink:cufflink@localhost:5432/cufflink \
NATS_URL=nats://localhost:4222 \
KEYCLOAK_URL=http://localhost:8180 KEYCLOAK_REALM=cufflink \
REDIS_URL=redis://localhost:6379 \
STORAGE_BACKEND=s3 S3_ENDPOINT=http://localhost:9000 S3_REGION=us-east-1 \
S3_ACCESS_KEY=rustfsadmin S3_SECRET_KEY=rustfsadmin S3_BUCKET=cufflink \
cargo run -p cufflink-platform

KEYCLOAK_ISSUER is not needed natively because KEYCLOAK_URL is already the browser-facing address.

cargo build --workspace
cargo test --workspace

Documentation

• Setup & operations — services, environment variables, tenants, production checklist, full API reference
• cufflink dev — a platform on your machine, with a tenant, a key and users
• Guides — feature walkthroughs
• WASM guide and WASM workers
• Testing — handlers in cargo test, and a platform inside the test
• Subscriptions, streams and schedules
• Schema ownership — adopted schemas, SQL migrations, the schema guard; The outbox — outbox, durable audit, webhook deliveries
• Database roles and secrets — for operators
• Tenant isolation — what an install hosting more than one tenant sets
• Authentication and Authorization
• Building on Cufflink
• Extensions — native services and NATS providers that WASM services call with ext_call
• Observability, Scaling, Audit
• Backup, Workspace, Packages
• Versions & platform features (with the v0.30.0, v0.29.0, R3 and R2 release notes) and Deployment notes
• Scoped permissions, Column permissions, Partner keys, External identity providers
• SQL with bound parameters, Service calls & the cache

Contributing

Bug reports, fixes, and proposals are welcome — see CONTRIBUTING.md. Security issues should be reported privately per SECURITY.md.

License

The platform and its server components are licensed under the Elastic License 2.0 (ELv2). You may use, modify and self-host them, but you may not provide them to others as a hosted or managed service.

The crates you build services with — cufflink, cufflink-fn, cufflink-types, cufflink-sdk-macros, cufflink-migrate, cufflink-pgcodec, cufflink-cli, cufflink-nats and cufflink-native — and the code under examples/ are licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option. Each crate's Cargo.toml states its license.

Contributions are accepted on the terms in CONTRIBUTING.md.