Pattern Specifications

Deep-dive into the core blueprint patterns. Each specification includes the YAML declaration format, generated endpoints, security model, and operational behaviour. These are the contracts that implementations must fulfil.

Every pattern here is a complete, working specification — not a tutorial. Declare the YAML, run weblisk generate, and get a production-ready implementation that follows the spec exactly. The full list of all 38 patterns is in the Blueprint Catalog.

api-rest

Define your data models once and generate spec-compliant CRUD endpoints automatically. Every generated endpoint follows Weblisk protocol conventions: JSON bodies, consistent error shapes, and deterministic URL patterns. Pagination, filtering, and sorting are built-in — not bolted on.

Blueprint Format

name: api-rest
version: 1.0.0

models:
  Task:
    fields:
      id:        uuid
      title:     string, required, max:255
      done:      boolean, default:false
      created:   timestamp, auto
      updated:   timestamp, auto

Generated Endpoints (per model)

Built-in Query Features

• Pagination: Cursor-based via limit and cursor query parameters — no offset-based pagination (O(n) → O(1))
• Filtering: Field-level via query params (?done=false&owner_id=abc)
• Sorting: Via sort param (?sort=created:desc,title:asc)

One YAML declaration generates a type-safe, validated, paginated API with consistent error responses across every model. No ORM configuration, no route registration, no validation boilerplate.

auth-session

Server-side session authentication for traditional web applications. Users authenticate with credentials, receive a secure HTTP-only cookie, and subsequent requests are authenticated via that cookie. CSRF protection is included by default for all state-changing operations.

Blueprint Format

name: auth-session
version: 1.0.0

config:
  session_duration: 86400       # 24 hours
  cookie_name: wl_session
  csrf_header: X-CSRF-Token
  max_sessions_per_user: 5
  password_min_length: 8

Endpoints

How It Works

1. User sends credentials to POST /auth/login
2. Server creates a session record and sets a Set-Cookie header: HttpOnly, Secure, SameSite=Lax
3. Server returns a CSRF token in the response body
4. Client includes the CSRF token in the X-CSRF-Token header on all state-changing requests (POST, PUT, DELETE)
5. On logout, the server destroys the session and clears the cookie

Security

• Passwords hashed with bcrypt (cost ≥ 12) or argon2id — never stored in plaintext
• Session IDs are 256-bit crypto-random values
• Failed login returns a generic message — never reveals whether an email exists
• Constant-time comparison for session IDs and CSRF tokens
• Login rate-limiting recommended (10 attempts/minute per IP)
• Oldest sessions evicted when max_sessions_per_user is exceeded

auth-token

Stateless authentication using JWTs for short-lived access and opaque refresh tokens for session continuity. API keys are also supported for service-to-service communication. Permissions are scoped — each token declares exactly what it can access.

Blueprint Format

name: auth-token
version: 1.0.0

config:
  access_token_duration: 900     # 15 minutes
  refresh_token_duration: 604800 # 7 days
  issuer: weblisk
  scopes:
    - read
    - write
    - admin

Endpoints

Authentication Flow

1. Client sends credentials to POST /auth/token with requested scopes
2. Server returns a signed JWT (15-min TTL) + opaque refresh token (7-day TTL)
3. Client sends Authorization: Bearer <jwt> on protected requests
4. When the JWT expires, client exchanges the refresh token at POST /auth/refresh for a new pair
5. Refresh token rotation: old token invalidated on every refresh (prevents replay attacks)

JWT Claims

{
  "sub": "user-id",
  "iss": "weblisk",
  "iat": 1713264000,
  "exp": 1713264900,
  "scopes": ["read", "write"]
}

Scope Enforcement

Endpoints declare required scopes. The token's scopes must be a superset. Insufficient scopes return 403 Forbidden (not 401).

GET  /tasks       → requires: [read]
POST /tasks       → requires: [write]
POST /auth/apikey → requires: [admin]

API Keys

For service-to-service communication. Created via POST /auth/apikey (requires admin scope). Keys use the same Authorization: Bearer header as JWTs — the server distinguishes them by the wl_key_ prefix. Full key returned only on creation.

Security

• Refresh tokens stored as SHA-256 hashes — raw token never persisted
• API keys also stored as hashes with only a prefix shown on lookup
• JWT signing: HS256 for single-server, ES256 for distributed systems
• 30-second clock skew tolerance on JWT expiration
• Token endpoint rate-limited (10 requests/minute per IP)

api-ai

The intelligence backbone of a Weblisk server. Abstracts provider-specific details (OpenAI, Anthropic, Ollama, Cloudflare Workers AI) behind a universal contract so agents, domains, and application code interact with LLMs through a single interface. Rather than each component implementing its own provider integration, the api-ai pattern provides a centralised gateway with rate limits, usage tracking, and provider routing.

Blueprint Format

name: api-ai
version: 1.0.0

providers:
  ollama:
    type: local
    base_url: http://localhost:11434
    models: [llama3, codellama]
  openai:
    type: remote
    auth: bearer
    env_key: WL_AI_OPENAI_KEY
    models: [gpt-4o, gpt-4o-mini]
  anthropic:
    type: remote
    auth: x-api-key
    env_key: WL_AI_ANTHROPIC_KEY
    models: [claude-sonnet-4-20250514, claude-haiku-4-20250414]

defaults:
  provider: ollama
  model: llama3
  temperature: 0.7
  max_tokens: 4096

Endpoints

Key Capabilities

• Provider failover: If the primary provider returns a 5xx or times out, falls back to a secondary provider transparently
• Tool calling: /ai/chat supports tool definitions — the model can request function calls, and provider-specific formats are normalised automatically
• Streaming: stream: true returns Server-Sent Events with incremental tokens
• Schema validation: /ai/extract validates the returned JSON against the provided schema and retries once on validation failure
• Token tracking: Usage data is tracked per-agent via trace_id for cost attribution
• Multi-provider: Configure local (Ollama), remote (OpenAI, Anthropic), and platform (Cloudflare Workers AI) providers simultaneously

realtime-chat

Real-time messaging built on WebSockets with named channels, presence awareness, and persistent message history. HTTP endpoints handle channel management and history retrieval; the WebSocket connection handles live messaging.

Blueprint Format

name: realtime-chat
version: 1.0.0

channels:
  general:
    description: Default public channel
    max_members: 1000
    history_limit: 500
    auth: none
  team:
    description: Authenticated team channel
    max_members: 100
    history_limit: 1000
    auth: token

Endpoints

WebSocket Frame Types

Client → Server: message (send to channel), typing (typing indicator), ping (keep-alive).

Server → Client: connected (initial payload with members + history), message (new message), typing (another user typing), presence (user joined/left), pong, error.

Channel auth modes: none (public) or token (requires valid auth token from auth-session or auth-token blueprint).

webhook-inbound

Receive webhook payloads from external services (Stripe, GitHub, Twilio, etc.). Each source is configured with its own validation scheme (HMAC signatures, IP allowlists) and routed to a handler.

Blueprint Format

name: webhook-inbound
version: 1.0.0

sources:
  stripe:
    path: /webhooks/stripe
    signature:
      header: Stripe-Signature
      algorithm: hmac-sha256
      secret_env: STRIPE_WEBHOOK_SECRET
    events:
      - payment_intent.succeeded
      - invoice.paid
  github:
    path: /webhooks/github
    signature:
      header: X-Hub-Signature-256
      algorithm: hmac-sha256
      secret_env: GITHUB_WEBHOOK_SECRET
    events:
      - push
      - pull_request

Endpoints

Validation Flow

1. Read raw request body (preserve for signature verification)
2. Look up source configuration — 404 for unknown sources
3. Validate HMAC signature with constant-time comparison — 401 if invalid
4. Check event type against allowed list — filtered events return 200 (prevents retry loops)
5. Route to handler asynchronously

webhook-outbound

Send webhook notifications to registered subscriber endpoints. Events are signed with HMAC for integrity, delivered with exponential backoff retries, and tracked for observability.

Blueprint Format

name: webhook-outbound
version: 1.0.0

config:
  signing_algorithm: hmac-sha256
  max_retries: 5
  retry_backoff: exponential   # 1s, 2s, 4s, 8s, 16s
  timeout: 10
  event_types:
    - user.created
    - order.placed
    - order.shipped

Endpoints

Delivery Flow

1. Event occurs — find all active subscribers for that event type
2. Build payload, compute HMAC-SHA256 with subscriber's secret
3. POST to subscriber URL with X-Webhook-Signature, X-Webhook-ID, X-Webhook-Timestamp headers
4. 2xx response → delivered. Non-2xx → retry with exponential backoff (up to 5 retries)
5. All delivery attempts logged with status, response code, and duration