Pranor Documentation

Welcome to the Pranor documentation. Pranor is a unified, modular backend infrastructure engine with its own programming language, designed to build high-performance microservices with zero glue code.

💡 Documentation Version Selector

• 📘 Pranor v1.0 (Stable Docs) — Core 16 Infrastructure Modules (Gate, Pulse, Vault, Auth, Mesh, etc.)
• 🚀 Pranor v2.0 (AI Execution Fabric Docs) — Governed AI Agent Execution Layer (std/graph, std/decision, std/agent, std/memory, std/eval, std/flow)

Quick Navigation

Modules

Install

# macOS/Linux
brew tap vyuvaraj/pranor && brew install pranor

# Windows
scoop bucket add pranor https://github.com/vyuvaraj/scoop-pranor
scoop install pranor

# From source
git clone https://github.com/vyuvaraj/pranor && cd pranor/lang && go build -o pranor .

First Service

pranor init myapp && cd myapp && pranor run main.pnr --watch

v2.0 AI Execution Fabric (v2.0-dev — merges post v1.0 release)

Pranor v2.0 extends the ecosystem with a governed AI agent execution layer built on top of the existing infrastructure. All v2.0 modules are CGO-free (CGO_ENABLED=0) and follow the OSS/EE build-tag convention.

Branch: All v2.0 features live on v2.0-dev. See v2.0 modules docs for full API reference.

Getting Started with Pranor

Build and deploy a backend service in 5 minutes.

Prerequisites

• Go 1.22+ installed (download)
• A terminal (bash, PowerShell, or cmd)

Install

macOS / Linux (Homebrew)

brew tap vyuvaraj/pranor
brew install pranor

Windows (Scoop)

scoop bucket add pranor https://github.com/vyuvaraj/scoop-pranor
scoop install pranor

From Source

git clone https://github.com/vyuvaraj/pranor.git
cd pranor/lang
go build -o pranor .
# Add to PATH or move to /usr/local/bin

Verify

pranor --version

Create Your First Service

pranor init myapp
cd myapp

This creates a main.pnr file:

server "8080"
database "sqlite://app.db"

migration "create_users" {
    db.query("CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE
    )")
}

export route "GET" "/api/users" (req) {
    let users = db.query("SELECT * FROM users")
    return { "users": users }
}

export route "POST" "/api/users" (req) {
    let name = req.body.name
    let email = req.body.email
    db.query("INSERT INTO users (name, email) VALUES (?, ?)", name, email)
    return { "status": "created" }
}

Run

pranor run main.pnr --watch

Your API is now running at http://localhost:8080. The --watch flag auto-reloads on file changes.

Test It

# Create a user
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# List users
curl http://localhost:8080/api/users

Build for Production

pranor build main.pnr -o myapp
./myapp  # Single binary, no runtime needed

Add More Capabilities

Pranor modules extend your service without glue code:

// Add a scheduled task
every 5m {
    log.info("Running cleanup...")
    db.query("DELETE FROM sessions WHERE expires_at < datetime('now')")
}

// Add caching
cache "in-memory"

export route "GET" "/api/users/:id" (req) {
    let cached = cache.get("user:" + req.params.id)
    if cached != nil { return cached }
    
    let user = db.query("SELECT * FROM users WHERE id = ?", req.params.id)
    cache.set("user:" + req.params.id, user, 300)
    return user
}

Deploy

# Docker
pranor deploy --target docker

# Kubernetes
pranor deploy --target k8s --namespace production

What's Next

• Language Reference — Full syntax guide
• Module Docs — Gate, Pulse, Vault, Auth, and more
• Deployment Guide — Production Docker/K8s setup
• Architecture Overview — How modules connect

Pranor: A Programming Language for Background Services

Pranor is a modern, high-level DSL (Domain-Specific Language) designed specifically for building background services, schedulers, event-driven applications, and API microservices. It compiles directly into native binaries via Go code generation, providing high performance, low resource consumption, and rapid development.

Table of Contents

• Key Features
• Getting Started
• Editor Support
• CLI Commands Reference
• Language Syntax Guide
• Multi-File Import System
• Async & Concurrent Primitives
• Multi-Target Code Generation
• Breaking Change Detector
• Web Playground
• Standard Library
• Package Management
• Testing Support
• Compilation & Deployment
• Documentation

Key Features

• Declarative Infrastructure: Routes, schedulers, pub/sub, databases, caches, and WebSockets as language keywords — not library calls.
• Compiles to Native Binaries: Go code generation → single binary deployment. No runtime dependencies.
• Optional Static Typing: Gradual type system with int, float, string, bool, optional types (T?), union types (T | error), and generics with constraints.
• 48 Standard Library Modules: Auth, JWT, retry, circuit breaker, pagination, CORS, rate limiting, validation, and more — written in Pranor itself.
• Built-in Test Framework: test "name" { assert expr } blocks with structured assertion messages.
• Multiple Database Backends: SQLite, PostgreSQL, Oracle, MongoDB — same db.query() API.
• Multiple Broker Backends: Kafka, NATS, RabbitMQ, MQTT — same subscribe/publish syntax.
• Concurrency Primitives: spawn, async/await, channels, worker pools.
• Middleware & Auth: Declarative middleware with use [auth, logging] on routes.
• Python Interop: Call Python scripts via extern fn bindings.
• Go Package FFI: Import any Go package with pranor add <package> and auto-generated declarations.
• VS Code Extension: Full LSP with diagnostics, autocomplete, hover, go-to-definition, and 30+ snippets.
• OpenTelemetry & Prometheus: Built-in tracing and metrics export.
• Docker Support: pranor dockerize generates production-ready Dockerfiles.
• Multi-File Import System: Import types and schemas across .pnr files with cross-file type resolution and circular import detection.
• async Task & concurrent {} Primitives: First-class language support for async task execution and parallel concurrent blocks.
• Multi-Target Code Generation: Generate Rust (pranor generate --lang rust) or Python (pranor generate --lang python) client code from .pnr service definitions.
• Breaking Change Detector: pranor diff old.pnr new.pnr detects field removals, type changes, and new required fields — safe to use in CI pipelines.
• Zero-Install WASM Playground: Try Pranor in the browser at playground.pranor.dev — runs the full compiler in WebAssembly, no install required.

Getting Started

Prerequisites

• Go: Version 1.22 or higher is required to build the compiler and execute Go-transpiled code.
• Python 3.x: Optional (needed if using Python external functions).

Install via Scoop (Windows)

scoop bucket add pranor https://github.com/vyuvaraj/scoop-pranor
scoop install pranor

Install via Homebrew (macOS / Linux)

brew tap vyuvaraj/pranor
brew install pranor

Install via Script (Windows)

irm https://raw.githubusercontent.com/vyuvaraj/Pranor/main/release-scripts/install.ps1 | iex

Build from Source

git clone https://github.com/vyuvaraj/Pranor.git
cd Pranor
go build -o pranor.exe .

Add the binary to your system PATH for global access.

Editor Support

VS Code Extension

Install Pranor Language Support from the VS Code Marketplace (or from .vsix in the repo):

• Syntax highlighting for .pnr files
• Real-time diagnostics (type errors, unused variables, missing returns)
• Autocomplete and hover information
• Go-to-definition across files
• 30+ code snippets (route, fn, struct, test, every, subscribe, etc.)
• Commands: Run (Ctrl+Shift+R), Build (Ctrl+Shift+B), Test (Ctrl+Shift+T)
• Format on save

CLI Commands Reference

Language Syntax Guide

Core Architecture Statements

Pranor allows you to declare global settings and connections dynamically or using values loaded from environment variables:

// Declare port dynamically from environment variables
server env("PORT")

// Setup global message broker (options: "in-memory", or Kafka address)
broker "in-memory"

// Setup databases (SQLite, PostgreSQL, Oracle, MongoDB)
database "sqlite://service_data.db"
database env("DATABASE_URL")

// Setup in-memory cache
cache "in-memory"

Static Typing & Type Annotations

Pranor supports optional static typing on variables and function signatures. Providing types compiles them directly into native Go types, skipping the performance overhead of runtime interface{} conversions.

Supported types: int, string, bool.

Variable Type Annotations

Specify types using : type after the identifier:

let count: int = 100
let label: string = "Items in queue"
let isActive: bool = true

Function Signature Type Annotations

Specify parameter and return types to optimize function calls and compiler math:

fn calculateTotal(base: int, tax: int) -> int {
    let result: int = base + tax
    return result
}

Schedulers (every & cron)

Easily define background routines that run periodically or at scheduled times.

Interval Scheduler

Runs a block of code at a specific time duration (e.g., s for seconds, m for minutes, h for hours).

every 5s {
    log.info("System healthcheck running...")
}

Cron Scheduler

Executes using standard cron patterns. Can load patterns from environment variables.

cron "0 */2 * * * *" {
    log.info("This runs every 2 minutes.")
}

// Load from environment variable
cron env("BACKUP_CRON") {
    log.warn("Starting system database backup...")
}

Web Servers & HTTP APIs (route)

Declare HTTP request endpoints with simple routes. Pranor handles request body parsing natively.

route "GET" "/status" (req) {
    log.info("Status check requested")
    return { 
        "status": "Pranor is operating normally", 
        "timestamp": time.now() 
    }
}

route "POST" "/webhook" (req) {
    let body = req.body
    log.info("Received body payload: ", body)
    return { "received": true }
}

Pub/Sub Broker (publish & subscribe)

Publish event messages and register subscriptions.

// Publish message onto a topic channel
publish "events.incoming" { "user_id": 101, "action": "login" }

// Subscribe to messages on a topic
subscribe "events.incoming" (msg) {
    log.info("Broker received event: ", msg)
}

Concurrency & Worker Pools (spawn)

You can execute operations asynchronously without blocking the main workflow thread.

Fire-and-Forget Goroutines

subscribe "incoming.tasks" (msg) {
    // Spawns a lightweight concurrent thread
    spawn processTask(msg)
}

Rate-Limited Worker Pools

Specify a worker limit to control resource consumption:

// Spawns up to 5 concurrent workers maximum
spawn(5) handleHeavyCalculation(data)

Database Operations (db.query)

Execute queries directly on the configured databases.

SQL Databases (SQLite, PostgreSQL, Oracle)

Supports query parsing and placeholders (? translates automatically to appropriate placeholders like $1 dynamically for PostgreSQL).

// Create schema table on startup
db.query("CREATE TABLE IF NOT EXISTS metrics (id INTEGER PRIMARY KEY, ts TEXT)")

// Insert records
db.query("INSERT INTO metrics (ts) VALUES (?)", time.now())

// Read records
let results = db.query("SELECT * FROM metrics LIMIT 5")
log.info("Metrics: ", results)

MongoDB Operations

Executes collection queries using standardized document queries:

let result = db.query("insert", "logs", "{\"service\": \"Pranor\", \"action\": \"db_test\"}")

Cache Operations (cache.set & cache.get)

Leverage native in-memory caching to save and read states quickly:

// Set key with cache TTL (Time to Live)
cache.set("session_user_1", { "id": 1, "role": "admin" }, "10m")

// Fetch value from cache
let session = cache.get("session_user_1")
log.info("Active Session: ", session)

S3 & Pranor Vault Client Operations (s3)

Interact with S3-compatible endpoints or a Pranor Vault gateway using the native s3 runtime functions. You can also import the helper wrapper from the standard library:

import { newClient, put, get, deleteObject, list, at, search } from "stdlib/s3.pnr"

// Initialize client
let client = newClient("http://localhost:8080", "admin", "adminsecret")

// Create and configure a bucket
client.createBucket("my-bucket")
client.setBucketVersioning("my-bucket", true)

// Upload and retrieve objects
client.put("my-bucket", "config.json", "{\"status\": \"active\"}")
let content = client.get("my-bucket", "config.json")
log.info("Content: ", content)

// Time-travel to retrieve previous versions of an object (Pranor Vault only)
let historicalContent = client.at("my-bucket", "config.json", "2026-06-15T09:00:00Z")

// Perform semantic search queries (Pranor Vault only)
let searchResults = client.search("my-bucket", "find active config files", 5)

Python Interoperability (extern fn)

Map complex algorithms or specialized Python libraries directly to Pranor functions:

// Map external Python method
extern fn analyzeText(text) from "python:./scripts/analyzer.py:analyze"

let result = analyzeText("Hello world!")
log.info("Python output: ", result)

Built-in Functions & Utilities

JSON Support

let obj = json.parse("{\"status\": true}")
let rawString = json.stringify(obj)

String Interpolation (f-strings)

let name = "Pranor"
let statusMessage = f"System: {name} is running!"

Pattern Matching (match)

match eventType {
    "PAYMENT_COMPLETED" => {
        log.info("Processing checkout success...")
    }
    "USER_LOGOUT" => {
        log.info("Cleaning session...")
    }
    _ => {
        log.warn("Unknown event category received")
    }
}

Exception Handling (try-catch)

try {
    let res = http.get("http://invalid-url.com")
} catch (err) {
    log.error("HTTP request failed: ", err)
}

Web Playground

Pranor includes an interactive Web Playground for trying the language in-browser.

• WASM Compiler: Syntax analysis and formatting run client-side
• Sandbox Runner: Compiles and executes code server-side with auto-termination

go build -o web_playground/server/server.exe web_playground/server/main.go
./web_playground/server/server.exe
# Open http://localhost:8080

Standard Library

Pranor ships with 48 importable modules written in Pranor itself:

Import with:

import { hashPassword, verifyPassword } from "stdlib/crypto"
import { ok, notFound, created } from "stdlib/response"
import { retry } from "stdlib/retry"

Package Management

Publishing

pranor publish <package-dir>

Installing

pranor install <package-name>

Using

import { Helper, helperFunc } from "mypkg"

Resolves to packages/mypkg/index.pnr or packages/mypkg/main.pnr. Only export-marked declarations are accessible.

Testing Support

Pranor includes a native test harness built into the language itself. This makes it trivial to write unit tests alongside your code and verify logic without external framework setups.

Defining Tests

Add test blocks and use the assert statement to check variables:

fn doubleValue(val) {
    return val * 2
}

test "doubling math verification" {
    assert doubleValue(2) == 4
    assert doubleValue(5) == 10
}

test "check string comparison" {
    let val = "Pranor" + "Lang"
    assert val == "ServLang"
}

Running Tests

Execute:

pranor test test_sample.pnr

Output:

Running tests from test_sample.pnr...
=== RUN   Test_DoublingMathVerification
--- PASS: Test_DoublingMathVerification (0.00s)
=== RUN   Test_CheckStringComparison
--- PASS: Test_CheckStringComparison (0.00s)
PASS
ok  	pranor/.build	1.518s

Compilation & Deployment

When pranor build or pranor test is executed, the compiler compiles the input .pnr code into a temporary directory called .build.

Inside .build:

1. service.go: Synthesizes code for all declarations, routes, and background routines.
2. main.go: Provides the service runtime engine and entry points.
3. pranor_test.go: Aggregates the test blocks translated to Go's native testing framework.

The output binary compiles out all debug logs and features a fast, low-overhead native runtime engine.

Documentation

• Language Reference — Full syntax and type system
• Getting Started — First project walkthrough
• Standard Library — All modules documented
• CLI Reference — All commands and flags
• Deployment Guide — Docker, TLS, observability
• Examples — Examples & technical articles

Multi-File Import System

Pranor supports splitting service definitions across multiple .pnr files. Types and schemas defined in one file can be imported and used in another:

// types/user.pnr
type User {
    id:    string
    name:  string
    email: string
}

// services/auth.pnr
import "./types/user.pnr"

route POST "/api/users" {
    body: User
    handler: createUser
}

Features:

• Cross-file type resolution with full type checking
• Circular import detection with descriptive error messages
• Wildcard imports: import "./types/*"
• Re-export: export type AdminUser extends User { role: string }

Async & Concurrent Primitives

Pranor provides first-class async and concurrent language constructs:

// Async task — fire and forget
async fn sendNotification(userID: string) {
    call POST "http://notifications/send" { userID }
}

route POST "/api/orders" {
    handler: fn(req) {
        let order = db.insert("orders", req.body)

        // Fire async — doesn't block the response
        async sendNotification(req.body.userID)

        return { order_id: order.id }
    }
}

// Concurrent block — run steps in parallel, collect results
route GET "/api/dashboard" {
    handler: fn(req) {
        let results = concurrent {
            orders:      call GET "http://orders/summary"
            inventory:   call GET "http://inventory/levels"
            analytics:   call GET "http://analytics/today"
        }

        return results  // all three completed in parallel
    }
}

Multi-Target Code Generation

Generate type-safe client code for other languages from your Pranor service definitions:

# Generate Go client (default — used within Pranor compilation)
pranor generate --lang go services/orders.pnr

# Generate Rust client
pranor generate --lang rust services/orders.pnr -o ./clients/rust/

# Generate Python client
pranor generate --lang python services/orders.pnr -o ./clients/python/

Generated Rust client:

#![allow(unused)]
fn main() {
// Auto-generated by `pranor generate --lang rust`
pub struct OrdersClient { base_url: String }
impl OrdersClient {
    pub async fn create_order(&self, body: CreateOrderRequest) -> Result<Order, Error> { ... }
    pub async fn get_order(&self, id: &str) -> Result<Order, Error> { ... }
}
}

Generated Python client:

# Auto-generated by `pranor generate --lang python`
class OrdersClient:
    def create_order(self, body: CreateOrderRequest) -> Order: ...
    def get_order(self, id: str) -> Order: ...

Breaking Change Detector

pranor diff compares two .pnr files (or two git revisions) and detects breaking API changes — safe to run in CI before merging:

pranor diff api/v1/orders.pnr api/v2/orders.pnr

Example output:

⚠️  BREAKING CHANGES DETECTED

[FIELD_REMOVED]   Order.discount_code      (line 12 → removed)
[TYPE_CHANGED]    Order.total: int → float  (line 8)
[REQUIRED_ADDED]  CreateOrderRequest.currency  (line 23 → now required)

✅ NON-BREAKING CHANGES

[FIELD_ADDED]     Order.created_at (optional)

Detected breaking change categories:

• Field removals from request/response types
• Type changes (e.g., int → string)
• Making optional fields required
• Route removal or method change
• Removing enum variants

Use in CI:

# GitHub Actions
- run: pranor diff main:api/orders.pnr HEAD:api/orders.pnr
  # Exits with code 1 if breaking changes detected

License

Apache 2.0 — see LICENSE

Links

• GitHub: github.com/vyuvaraj/pranor
• Playground: playground.pranor.dev — zero-install WASM browser playground
• VS Code Extension: Search "Pranor Language Support" in Extensions
• Issues: github.com/vyuvaraj/pranor/issues

Pranor Standard Library

Reusable .pnr modules for common service patterns. Import what you need:

import { ok, notFound } from "stdlib/response.pnr"
import { requireAuth, bearerToken } from "stdlib/auth.pnr"

Module Index

Categories

Security

• auth.pnr — Token extraction, bearer/basic auth, auth guards
• crypto.pnr — Password hashing, HMAC signing, token generation
• jwt.pnr — JWT encode/decode/expiry (lightweight; use pranor add github.com/golang-jwt/jwt/v5 for production)

HTTP

• response.pnr — Standard HTTP response builders (ok, notFound, etc.)
• pagination.pnr — Page offset calculation, response envelope
• middleware.pnr — CORS headers, request ID generation, preflight detection
• http_client.pnr — JSON GET/POST wrappers, status code helpers

Utilities

• datetime.pnr — Timestamps, expiry checks, duration formatting
• strings_util.pnr — Slugify, truncate, capitalize, pattern matching
• collections.pnr — Array utilities (unique, flatten, chunk, first/last)

Config & Environment

• env.pnr — Required env vars, defaults, type coercion (int/bool)

Resilience

• retry.pnr — Exponential backoff calculation

Messaging

• events.pnr — In-process event bus (emit/on pattern)

Testing

• testing_helpers.pnr — Expressive assertions for test blocks

Operations

• health.pnr — Custom health check builders
• graceful.pnr — Shutdown state, connection draining, drain detection

Scheduling

• scheduler.pnr — Dynamic runtime scheduling beyond every/cron

Integration

• webhook.pnr — Outgoing webhook payloads, signature verification, retry records
• cors.pnr — CORS header generation, origin checking, preflight responses

Concurrency

• semaphore.pnr — Named semaphores with slot tracking and utilization metrics

Processing

• batch.pnr — Accumulate-and-flush batch pattern with size tracking
• job.pnr — Background job lifecycle (pending → running → completed/failed)

Reliability

• idempotency.pnr — Idempotency key pattern for deduplication
• dlq.pnr — Dead letter queue for failed message tracking

Multi-tenancy

• tenant.pnr — Tenant extraction from requests, scoped config/cache/DB keys

Compliance

• audit.pnr — Structured audit trail (actions, access, auth, denied events)

Usage Example

import { requireAuth, bearerToken } from "stdlib/auth.pnr"
import { ok, badRequest } from "stdlib/response.pnr"
import { required, isEmail } from "stdlib/validation.pnr"
import { envOrDefault } from "stdlib/env.pnr"

server envOrDefault("PORT", "8080")

route "POST" "/api/users" (req) {
    let authErr = requireAuth(req)
    if authErr != nil {
        return authErr
    }

    let errors = validate(req.body, {
        "email": "required,email",
        "name": "required"
    })
    if errors != nil {
        return badRequest(errors)
    }

    return ok({ "created": true })
}

Contributing

Add new modules as stdlib/<name>.pnr. Export functions with export fn. Follow existing patterns:

• Pure functions where possible
• No side effects unless explicitly documented
• Use interface{} params (no type annotations) for maximum flexibility

Pranor CLI Reference

The pranor command is the single entry point for all development and deployment tasks.

Usage

pranor <command> [options] [arguments]

Commands

Development

Package Management

Deployment

Infrastructure

Tooling

Global Flags

Environment Variables

Examples

# Create and run a project
pranor init my-api
cd my-api
pranor run main.pnr --watch

# Build for production
pranor build main.pnr -o my-api --target linux/amd64

# Run tests with coverage
pranor test main.pnr --cover

# Deploy to Docker
pranor deploy --target docker

# Add a package
pranor add github.com/google/uuid

Blog & Articles

Technical articles about Pranor architecture and design decisions.

These articles were originally published on Medium and provide deep-dives into individual modules.

Tooling & IDE Support

Pranor provides dedicated developer tooling and IDE integration to support language editing, code refactoring, diagnostics, and visual cloud control.

1. VS Code Extension (pranor-vscode)

The official Pranor Platform & Language Tools extension converts VS Code into an integrated control plane for your entire microservice infrastructure.

Installation

• Search for Pranor Platform & Language Tools in the VS Code Marketplace, or install the .vsix package:

  code --install-extension pranor-vscode-1.0.0.vsix
  

Key Features & Control Panels

• Language Intelligence: Syntax highlighting, formatting, diagnostics, and code lens shortcuts for .pnr files.
• Interactive API Client Panel (pranor.apiClient): In-editor HTTP test runner targeting Pranor Gate API routers.
• Live Event Stream & DLQ Tailer Panel (pranor.tailPulseEvents): Tail Pranor Pulse event topics in real-time with one-click Dead Letter Queue (DLQ) replay.
• S3 & Vector Search Explorer (pranor.vectorSearch): Browse Pranor Vault object buckets and run natural language HNSW cosine vector searches directly inside VS Code.
• Live Distributed Flamegraph Viewer (pranor.flamegraphLogs): Trace execution bottlenecks with CPU/latency flamegraphs correlated side-by-side with log entries by trace_id.
• Visual Secret Console (pranor.secretConsole): Manage cluster master keys, unseal vault stores, and inspect environment secrets.
• Multi-Cluster Infrastructure Dashboard (pranor.clusterDeployments): Monitor multi-region cluster health and trigger one-click blue/green canary deployments.

2. Language Server Protocol (pranor-lsp)

pranor-lsp is an enterprise-grade Language Server implementing the Language Server Protocol (LSP) specification for standard editor integration (VS Code, Neovim, Emacs, Sublime Text, JetBrains).

Capabilities

• Workspace-Wide Rename (textDocument/rename): Safe multi-file refactoring emitting WorkspaceEdit diffs across all workspace .pnr files.
• Auto-Imports & Code Actions (textDocument/codeAction): Quick-fixes including missing use std/... imports and error handler stubs.
• Fuzzy Workspace Symbol Search (workspace/symbol): High-performance background symbol indexing (Ctrl+T / Cmd+T).
• Call Hierarchy Navigation (textDocument/prepareCallHierarchy): Visual incoming and outgoing call tree inspection for functions and HTTP routes.
• Chained Type Inference (textDocument/completion): Context-aware member completions for chained calls (e.g. db.query().first(), encoding.base64.).
• Document Highlighting & Incremental Sync (textDocument/documentHighlight): Zero-latency symbol occurrence highlighting on cursor focus.

Standalone Server Usage

Start pranor-lsp via standard stdin/stdout JSON-RPC:

pranor lsp
# or directly:
pranor-lsp

Pranor Gate — API Gateway & Ingress Router

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/gate
Default Port: 8080
License: AGPL-3.0 (OSS) / Enterprise License (EE with eBPF, GraphQL Federation, Geo-IP Steering)

Overview

Pranor Gate is a high-performance API gateway and reverse proxy that routes, secures, and transforms traffic between clients and upstream services. It features WASM-based plugin extensibility, AI-aware traffic management (prompt guard, semantic caching, PII redaction, token billing), weighted canary/blue-green deployments with automatic promotion, circuit breaking, SSE passthrough, WebSocket proxying, and a declarative per-route configuration model.

Pranor Gate can run as:

• A standalone binary with local JSON configuration
• An integrated module within the Pranor ecosystem with S3-based dynamic config, JWT auth, OTel tracing, and Console visibility
• An edge proxy with Let's Encrypt auto-TLS or dynamic certificate fetching from Pranor Secret

Table of Contents

• Key Features
• Architecture
• Installation & Deployment
• Configuration
• API Reference
• Routing & Traffic Management
• WASM Plugin System
• AI Guard & LLM Routing
• Security
• Observability
• Client Libraries & CLI
• Enterprise Edition
• Operational Runbook

Key Features

Architecture

graph TD
    subgraph Edge ["Global Ingress Layer"]
        DNS["Geo-IP Anycast DNS"]
        XDP["eBPF XDP Packet Filter"]
    end

    subgraph Security ["Zero-Trust Security and WASM Engine"]
        TLS["PCIe Hardware TLS Offload"]
        WASM["WASM Security Sandbox"]
        PromptGuard["AI Prompt Injection Guard"]
    end

    subgraph Core ["Proxy Router and Rate Limiter"]
        CRDT["Global CRDT Rate Limiter"]
        Router["Dynamic Reverse Proxy"]
    end

    subgraph Upstream ["Upstream Microservices"]
        AIModel["LLM / Model Service"]
        Microservice["gRPC / REST Microservice"]
    end

    DNS --> XDP
    XDP --> TLS
    TLS --> WASM
    WASM --> PromptGuard
    PromptGuard --> CRDT
    CRDT --> Router
    Router -->|mTLS| AIModel
    Router -->|mTLS| Microservice

Request Processing Sequence & WASM Execution Flow

sequenceDiagram
    autonumber
    participant Client as Client Application
    participant Gate as Pranor Gate Ingress
    participant Auth as Pranor Auth / JWT Validator
    participant WASM as WASM Plugin Sandbox
    participant AI as AI Prompt Guard
    participant Service as Upstream Microservice

    Client->>Gate: HTTP Request / POST /v1/ai/prompt
    Gate->>Auth: Validate JWT / SPIFFE SVID Token
    Auth-->>Gate: Token Validated (Claims + Tenant Context)
    Gate->>WASM: Execute Request Transformer (WASM)
    WASM-->>Gate: Transformed Headers & Body
    Gate->>AI: Evaluate Prompt Injection & PII Redaction
    AI-->>Gate: Sanitized Prompt & Risk Score (Passed)
    Gate->>Service: Forward Request (mTLS + Retrying Transport)
    Service-->>Gate: Response Stream (200 OK)
    Gate->>WASM: Execute Response Transformer (WASM)
    WASM-->>Gate: Final Formatted Payload
    Gate-->>Client: Streamed HTTP Response + X-Token-Cost

Ecosystem Cross-Module Integration

Pranor Gate acts as the front door for the entire Pranor platform, seamlessly interfacing with core infrastructure services:

• Pranor Auth: Automatically verifies incoming JWT signatures, SAML claims, and SPIFFE/SPIRE x509 workload identities (PRANOR_JWT_SECRET).
• Pranor Secret: Dynamically fetches and auto-rotates TLS server certificates and client mTLS credentials without restarting the proxy.
• Pranor Trace: Generates W3C-compliant traceparent OpenTelemetry headers, emitting distributed trace spans for every proxied request.
• Pranor Console: Streams real-time throughput, p99 latency histograms, and active WASM plugin health metrics directly to the control plane dashboard.
• Pranor Vault: Pulls dynamic S3-backed JSON route configurations and uploads recorded JSONL traffic replay logs.

Installation & Deployment

Binary

cd pranor/gate
go build -o pranor-gate .
./pranor-gate

Docker

docker run -p 8080:8080 ghcr.io/vyuvaraj/pranor-gate:latest

Docker Compose

services:
  gate:
    image: ghcr.io/vyuvaraj/pranor-gate:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.json:/app/config.json
    environment:
      - PRANOR_JWT_SECRET=your-secret

As Part of Pranor Ecosystem

When running under the Pranor platform, Gate integrates automatically with Auth (JWT/mTLS), Secret (dynamic certificates), Trace (OTel spans), and Console (dashboard visibility). Configuration can be pulled from an S3-compatible store for centralized management.

Configuration

JSON Config (config.json)

{
  "addr": ":8080",
  "auth_token": "gateway-secret-token",
  "tls_cert": "",
  "tls_key": "",
  "routes": [
    {
      "prefix": "/api/v1/services",
      "target": "http://127.0.0.1:8081",
      "middleware": "uppercase",
      "rate_limit_rpm": 120,
      "cache_ttl_seconds": 60,
      "access_log": true
    },
    {
      "prefix": "/ai/v1",
      "target": "http://127.0.0.1:11434",
      "enable_semantic_cache": true,
      "enable_prompt_guard": true,
      "semantic_token_limit_per_min": 10000
    }
  ]
}

Environment Variables

CLI Flags

CLI Subcommands

API Reference

Base URL: http://localhost:8080
API Version: /api/v1/ (recommended) or /api/ (legacy)

GET /healthz

Liveness probe.

{"status":"UP","service":"pranor","version":"1.0.0"}

GET /readyz

Readiness probe. Same format as healthz.

GET /api/v1/routes

List all configured routes.

Response (200):

[
  {
    "prefix": "/api/v1/services",
    "target": "http://127.0.0.1:8081",
    "middleware": "uppercase",
    "rate_limit_rpm": 120
  }
]

POST /api/v1/routes

Register or update a route dynamically.

Request:

{
  "prefix": "/api/v2/users",
  "target": "http://users-service:8080",
  "rate_limit_rpm": 200,
  "cache_ttl_seconds": 30,
  "ip_allowlist": ["10.0.0.0/8"]
}

Response (200):

Route registered successfully

DELETE /api/v1/routes?prefix=/api/v2/users

Remove a route.

Response (200):

Route deleted successfully

POST /api/v1/admin/middleware/

Register a WASM middleware plugin at runtime.

Request: Raw .wasm binary as request body.

Response (200):

WASM Middleware auth-check compiled and registered

GET /api/v1/admin/connections

List active backend connections.

Response (200):

{
  "http://127.0.0.1:8081": 5,
  "http://127.0.0.1:8082": 2
}

DELETE /api/v1/admin/cache?prefix=/api/v1/data

Invalidate response cache entries.

Response (200):

{
  "status": "success",
  "entries_invalidated": 12,
  "prefix": "/api/v1/data"
}

POST /api/v1/admin/policy/reload

Hot-reload the dynamic IAM policy schema.

Request (optional body): Policy schema JSON.

Response (200):

{"status": "success", "message": "Policy schema updated"}

POST /api/v1/admin/policy/revoke

Revoke all sessions for a user.

Request:

{"username": "compromised-user"}

Response (200):

{"status": "success", "message": "Session revoked for user compromised-user"}

GET /api/v1/admin/ai-billing

Retrieve AI token usage and cost metrics.

Response (200):

{
  "total_tokens": 1523400,
  "total_cost_usd": 4.57,
  "per_tenant": {
    "tenant-a": {"tokens": 800000, "cost_usd": 2.40}
  }
}

POST /api/v1/admin/ai-billing

Set per-tenant AI budget limits.

Request:

{
  "tenant_id": "tenant-a",
  "max_cost_per_day_usd": 10.00,
  "max_tokens_per_minute": 50000
}

GET /api/v1/admin/ai-cost-attribution

Per-route AI token and cost attribution dashboard.

Response (200):

{
  "routes": [
    {
      "prefix": "/ai/v1",
      "total_tokens": 500000,
      "total_cost_usd": 1.50,
      "estimated_savings": 0.30
    }
  ],
  "summary": {
    "total_cost_usd": 4.57,
    "total_tokens": 1523400,
    "estimated_savings": 0.91,
    "savings_percent": 16.6
  }
}

GET /api/v1/admin/metrics/ws

WebSocket endpoint streaming real-time gateway metrics (RPS, error rate, active connections).

POST /api/v1/admin/console/sync

Synchronize full route configuration from Pranor Console.

Request:

{"routes": [...]}

GET /api/v1/admin/console/sync

Get current gateway state snapshot (routes, connections, metrics).

POST /api/v1/gitops/webhook

Trigger a git pull + config reload for GitOps-managed configuration.

Response (200):

{
  "status": "success",
  "message": "GitOps config sync completed successfully",
  "git_output": "Already up to date."
}

POST /api/v1/routes/register

Register a route via the compiler connector (for Pranor Lang integration).

GET /api/docs

Embedded interactive API documentation page.

GET /api/docs/openapi.json

Auto-generated OpenAPI specification from current routes.

Routing & Traffic Management

Prefix-Based Matching

Routes are matched by longest-prefix on the request URL path. The first matching route wins.

Weighted Canary / Blue-Green Deployments

Distribute traffic between stable and canary targets by weight:

{
  "prefix": "/api/v1/orders",
  "targets_weighted": [
    {"url": "http://orders-v1:8080", "weight": 90},
    {"url": "http://orders-v2:8080", "weight": 10}
  ],
  "canary_auto_promote": true,
  "canary_promote_step": 10,
  "canary_promote_sec": 60,
  "canary_max_error_rate": 0.01
}

The canary engine automatically:

1. Increments canary weight by canary_promote_step every canary_promote_sec seconds
2. Monitors error rate on the canary target
3. Rolls back to 100% stable if error rate exceeds canary_max_error_rate
4. Disables auto-promotion once canary reaches 100%

Load Balancing

Multiple targets support round-robin and least-connections strategies:

{
  "prefix": "/api/v1/users",
  "targets": ["http://users-1:8080", "http://users-2:8080", "http://users-3:8080"],
  "load_balancer": "least_conn"
}

Circuit Breaker

Automatically opens when upstream error rate exceeds threshold, preventing cascade failures. Half-open state probes recovery.

Backpressure Control

Per-route concurrency limiting with queue overflow:

{
  "max_concurrent_requests": 100,
  "max_queue_size": 500,
  "queue_timeout_ms": 5000
}

Returns 503 Service Unavailable when queue is full, 504 Gateway Timeout on queue timeout.

Response Caching

{
  "cache_ttl_seconds": 60,
  "cache_methods": ["GET"]
}

WASM Plugin System

Architecture

WASM middlewares are compiled via wazero (pure-Go WebAssembly runtime, no CGO). Plugins receive the request, can transform headers/body, and return modified content.

Registering a Plugin

# From registry
pranor-gate install jwt-auth

# Upload directly
curl -X POST http://localhost:8080/api/v1/admin/middleware/my-filter \
  -H "Authorization: Bearer gateway-secret-token" \
  --data-binary @my-filter.wasm

Per-Route Assignment

{
  "prefix": "/api/v1/data",
  "middleware": "my-filter",
  "response_middleware": "response-transform"
}

WASM A/B Testing

Split traffic between different WASM middleware versions:

{
  "wasm_split": {
    "targets": [
      {"middleware_name": "filter-v1", "weight": 80},
      {"middleware_name": "filter-v2", "weight": 20}
    ]
  }
}

Policy DSL Compilation

Write human-readable policies and compile to WASM:

# auth.policy
allow GET /api/public/*
deny POST /api/admin/* if header.role == "viewer"
allow * * if header.x-internal == "true"

pranor-gate policy compile auth.policy -o auth.wasm

AI Guard & LLM Routing

Prompt Guard

Detects and blocks prompt injection attempts on AI-routed traffic:

{"prefix": "/ai/v1", "prompt_guard": true}

PII Redaction

Masks sensitive data (emails, SSN, credit cards) before forwarding to LLM backends:

{"prefix": "/ai/v1", "pii_redact": true}

Semantic Cache

Caches LLM responses and returns cached versions for semantically similar prompts (cosine similarity > 0.85):

{"prefix": "/ai/v1", "semantic_cache": true}

LLM Routing with Fallback

Route to a primary model with automatic fallback on low confidence:

{
  "llm_routing": {
    "primary": {"url": "http://ollama:11434", "model": "llama3"},
    "fallback": {"url": "https://api.openai.com", "model": "gpt-4"},
    "confidence_header": "X-Confidence",
    "min_confidence": 0.7
  }
}

Semantic Rate Limiting

Token-based rate limiting for LLM routes (tokens-per-minute rather than requests-per-minute):

{"semantic_rate_limit": true, "semantic_token_limit_per_min": 10000}

Prompt A/B Testing

Route different prompt templates to measure response quality.

Security

Bearer Token Auth

Set auth_token in config. All non-health endpoints require:

Authorization: Bearer gateway-secret-token

JWT Authentication

When PRANOR_JWT_SECRET is set, validates JWT Bearer tokens. Supports policy versioning — stale tokens get X-Token-Refresh: true header.

Dynamic Secret Fetching

Gate can fetch TLS certificates and JWT secrets dynamically from Pranor Secret at startup.

mTLS to Upstreams

Per-route client certificate for backend authentication:

{
  "client_cert_path": "/certs/client.crt",
  "client_key_path": "/certs/client.key",
  "root_ca_path": "/certs/backend-ca.crt"
}

Multi-Tenant API Keys

Per-key rate limits, route restrictions, and tenant isolation:

{"require_api_key": true, "allowed_tenants": ["tenant-a", "tenant-b"]}

IP Allowlist / Blocklist

{
  "ip_allowlist": ["10.0.0.0/8", "192.168.1.0/24"],
  "ip_blocklist": ["1.2.3.4"]
}

Request Body Size Limits

Per-route body size enforcement (default 10MB):

{"max_body_size": 5242880}

Session Revocation

Instant session revocation via admin API without waiting for token expiry.

Dynamic IAM Policy (ServPolicy)

Upload OPA-style policy schemas that Gate evaluates inline per request.

Observability

Metrics

WebSocket Live Metrics

Connect to /api/v1/admin/metrics/ws for 1-second streaming metrics updates.

Access Logging

Structured JSONL access logs per route:

{
  "timestamp": "2026-01-15T10:00:00Z",
  "method": "GET",
  "path": "/api/v1/users/123",
  "status": 200,
  "latency_ms": 42,
  "client_ip": "10.0.1.5",
  "upstream": "http://users:8080"
}

OpenTelemetry Tracing

Every proxied request gets an OTel span with method, route, status code, and upstream latency.

Terminal Dashboard

pranor-gate dashboard

Live TUI showing real-time RPS, P99 latency, circuit breaker state, cache hit rate.

Client Libraries & CLI

cURL

# Register a route
curl -X POST http://localhost:8080/api/v1/routes \
  -H "Authorization: Bearer gateway-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"/api/v2/users","target":"http://users:8080","rate_limit_rpm":100}'

# Upload WASM middleware
curl -X POST http://localhost:8080/api/v1/admin/middleware/auth-check \
  -H "Authorization: Bearer gateway-secret-token" \
  --data-binary @auth-check.wasm

# Invalidate cache
curl -X DELETE "http://localhost:8080/api/v1/admin/cache?prefix=/api/v1/data" \
  -H "Authorization: Bearer gateway-secret-token"

Pranor CLI

pranor gate routes list
pranor gate routes add --prefix /api/v2 --target http://backend:8080 --rate-limit 100
pranor gate middleware install jwt-auth
pranor gate dashboard
pranor gate replay --log traffic.jsonl --middleware filter.wasm

Enterprise Edition

Operational Runbook

Route not matching / 502 Bad Gateway

1. Check /api/v1/routes for the configured routes
2. Verify the request path has the correct prefix
3. Ensure the upstream target is reachable from the gateway
4. Check circuit breaker state via metrics

High latency on specific route

1. Check /api/v1/admin/connections for connection count
2. Review backpressure settings — max_concurrent_requests may be too low
3. Check if circuit breaker is in half-open state (probing slowly)
4. Look at upstream health via WebSocket metrics stream

Rate limiting kicking in unexpectedly

1. Verify rate_limit_rpm is set correctly on the route
2. Check if Redis-based distributed limiting is configured — all instances share state
3. Per-API-key limits may be more restrictive than route limits
4. Review semantic token rate limits for AI routes

WASM middleware failing

1. Check gateway logs for WASM compilation errors
2. Use pranor-gate replay --log traffic.jsonl --middleware broken.wasm to test offline
3. Verify WASM module exports the correct ABI functions
4. Check if the middleware registry URL is reachable

Canary deployment not promoting

1. Check error rate on canary target — exceeding canary_max_error_rate causes rollback
2. Verify canary_auto_promote is true
3. Ensure at least 3 requests have hit the canary (minimum sample for error rate calculation)
4. Check canary_promote_sec interval — promotion may not have triggered yet

TLS certificate issues

1. If using auto-TLS, ensure port 80 is accessible for HTTP challenge
2. For Pranor Secret integration, verify PRANOR_SECRET_URL connectivity
3. Check certificate paths in config for file-based TLS
4. Review gateway startup logs for certificate loading errors

Versioning & Compatibility

• API is versioned at /api/v1/
• Legacy /api/ paths continue to work (internally mapped to v1)
• Configuration format is backward-compatible across minor versions
• WASM ABI is stable — plugins compiled for v1.0 work on all v1.x releases

Pranor Pulse — Async Event Broker & Message Queue

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/pulse
Default Ports: 8082 (HTTP), 61613 (STOMP)
License: AGPL-3.0 (OSS) / Enterprise License (EE with Raft, MirrorMaker, KMS Encryption)

Overview

Pranor Pulse is a multi-protocol message broker and event streaming platform that supports STOMP, Kafka wire protocol, and MQTT v5 simultaneously. It provides durable WAL-based persistence, WASM-powered message transforms, dead letter queues with intelligent triage, consumer groups, partitioned topics, priority queues, delayed/scheduled messages, schema validation, tiered cold storage offloading, and browser-native OPFS queue support.

Pranor Pulse can run as:

• A standalone binary with zero external dependencies (WAL file-backed)
• An integrated module within the Pranor ecosystem with mTLS, RBAC, OTel tracing, and Console visibility
• A Kafka-compatible broker accepting native Kafka producer/consumer clients
• A browser-embedded queue via OPFS for offline-first PWAs

Table of Contents

• Key Features
• Architecture
• Installation & Deployment
• Configuration
• API Reference
• Messaging Semantics
• Protocol Support
• Storage & Durability
• Security
• Observability
• Client Libraries & SDKs
• Enterprise Edition
• Operational Runbook

Key Features

Architecture

graph TD
    subgraph Adapters ["Multi-Protocol Wire Interface"]
        STOMP["STOMP 1.2 Listener :61613"]
        Kafka["Kafka Wire Decoder :9092"]
        MQTT["MQTT v5 Broker :1883"]
        HTTP["HTTP REST API :8082"]
    end

    subgraph Core ["Core Event Streaming Broker"]
        Registry["Topic Registry and Wildcard Matcher"]
        Dedup["Idempotent Dedup Window"]
        Schema["Schema Compatibility Inspector"]
        WASM["WASM Transform Pipeline"]
        Dispatch["Partition and Consumer Group Dispatcher"]
    end

    subgraph Storage ["WAL and Tiered Persistence Engine"]
        WAL["Write-Ahead Log Engine"]
        DLQ["Dead-Letter Queue Storage"]
        ColdStore["S3 Cold Storage Offloader"]
    end

    subgraph Timers ["Delayed Delivery and Recovery"]
        TimeWheel["TimeWheel Delayed Scheduler"]
        OffsetStore["Consumer Group Offset Store"]
    end

    STOMP --> Registry
    Kafka --> Registry
    MQTT --> Registry
    HTTP --> Registry
    Registry --> Dedup
    Dedup --> Schema
    Schema --> WASM
    WASM --> Dispatch
    Dispatch --> WAL
    WAL --> DLQ
    WAL -.-> ColdStore
    TimeWheel -.-> Dispatch
    OffsetStore -.-> Dispatch

Event Streaming & Consumer Dispatch Sequence Flow

sequenceDiagram
    autonumber
    participant Producer as Event Producer (Kafka / STOMP / REST)
    participant Pulse as Pranor Pulse Broker Core
    participant Dedup as Sliding Dedup Window
    participant WASM as WASM Transform Sandbox
    participant WAL as Hardware AES-NI WAL Storage
    participant Consumer as Consumer Group Subscriber
    participant DLQ as Dead-Letter Queue (DLQ)

    Producer->>Pulse: Publish Event (Topic: "orders.created", Payload)
    Pulse->>Dedup: Verify Message ID & Producer Sequence Number
    Dedup-->>Pulse: Unique Payload (Passed)
    Pulse->>WASM: Execute Topic Transform Pipeline (WASM)
    alt Transform Succeeded
        WASM-->>Pulse: Enriched Event Payload
        Pulse->>WAL: Append Payload to Active WAL Segment
        WAL-->>Pulse: Log Offset Committed
        Pulse->>Consumer: Dispatch Event Payload via Consumer Group Round-Robin
        Consumer-->>Pulse: Acknowledge Event Commit (Offset Updated)
    else Transform Failed / Processing Expiry
        WASM-->>Pulse: Exception / Transform Error
        Pulse->>DLQ: Route Event Payload to Dead-Letter Queue
        DLQ-->>Pulse: DLQ Entry Logged & AI Triage Suggested
    end

Ecosystem Cross-Module Integration

Pranor Pulse serves as the primary asynchronous message bus across the Pranor platform:

• Pranor Flow: Dispatches saga workflow execution steps, compensation triggers, and human-in-the-loop task events via Pulse topics.
• Pranor Vault: Receives closed WAL segments offloaded automatically to S3 object buckets for long-term cold archive retention.
• Pranor Trace: Propagates trace context headers across message boundaries, tracking event latency flamegraphs end-to-end.
• Pranor Console: Provides real-time event throughput dashboards, consumer group rebalance monitors, and 1-click DLQ message replay UI.
• Pranor Gate: Relays event streams to web clients via WebSocket upgrader and SSE stream passthrough.

Installation & Deployment

Binary

cd pranor/pulse
go build -o pranor-pulse .
./pranor-pulse

Docker

docker run -p 8082:8082 -p 61613:61613 ghcr.io/vyuvaraj/pranor-pulse:latest

Docker Compose

services:
  pulse:
    image: ghcr.io/vyuvaraj/pranor-pulse:latest
    ports:
      - "8082:8082"
      - "61613:61613"
    environment:
      - PRANOR_PULSE_WAL_PATH=/data/queue.wal
    volumes:
      - pulse-data:/data
volumes:
  pulse-data:

As Part of Pranor Ecosystem

When running under the Pranor platform, Pulse integrates automatically with Auth (JWT/mTLS), Trace (OTel spans), and Console (dashboard visibility). Multi-tenant topic namespacing is enforced automatically.

Configuration

Environment Variables

STOMP Credentials

Default credentials (configured in code, overridable via ecosystem auth):

• Username: admin
• Password: secret

HTTP API Auth Token

Default: secret-token (standalone mode). In ecosystem mode, full JWT/mTLS auth chain is used.

API Reference

Base URL: http://localhost:8082
API Version: /api/v1/ (recommended) or /api/ (legacy)

GET /healthz

Liveness probe.

{"status":"UP","service":"pranor","version":"1.0.0"}

GET /readyz

Readiness probe.

POST /api/v1/publish

Publish a message to a topic.

Request:

{
  "topic": "orders.created",
  "payload": "{\"order_id\":\"abc-123\",\"amount\":99.99}",
  "key": "abc-123",
  "priority": 5,
  "delay_ms": 0,
  "message_id": "msg-unique-001",
  "ttl_ms": 60000
}

Response (200):

{
  "status": "success",
  "topic": "orders.created",
  "processed_payload": "{\"order_id\":\"abc-123\",\"amount\":99.99}"
}

Backpressure Response (503):

{
  "error": "queue capacity exceeded: backpressure active",
  "code": "ERR_BACKPRESSURE"
}

POST /api/v1/publish/batch

Publish multiple messages atomically.

Request:

{
  "messages": [
    {"topic": "events.user", "payload": "{\"action\":\"login\"}"},
    {"topic": "events.user", "payload": "{\"action\":\"page_view\"}"}
  ]
}

GET /api/v1/topics

List all topics with metadata.

Response (200):

{
  "topics": [
    {
      "name": "orders.created",
      "subscribers": 3,
      "partitions": 3,
      "has_transform": true,
      "dlq_topic": "orders.created.dlq"
    }
  ],
  "count": 1
}

POST /api/v1/topics/{topic}/transform

Register a WASM transform for a topic.

Request: Raw .wasm binary as request body.

Response (200):

WASM transform registered for topic orders.created

To clear a transform, send an empty body.

POST /api/v1/topics/{topic}/dlq

Register a Dead Letter Queue for a topic.

Request:

{"dlq_topic": "orders.created.dlq"}

GET /api/v1/topics/{topic}/dlq

List DLQ messages for a topic.

Response (200):

{
  "messages": [
    {
      "message_id": "dlq-1234567890",
      "source_topic": "orders.created",
      "original_payload": "{\"bad\":\"data\"}",
      "failure_reason": "WASM transform error: invalid field",
      "timestamp": 1706000000,
      "retry_count": 1
    }
  ],
  "total": 1,
  "dlq_topic": "orders.created.dlq"
}

GET /api/v1/topics/{topic}/dlq/summary

AI-powered DLQ analysis with failure pattern clustering.

GET /api/v1/topics/{topic}/dlq/triage

Intelligent DLQ triage with remediation suggestions.

POST /api/v1/topics/{topic}/dlq/requeue

Requeue a DLQ message (optionally patched) back to its source topic.

Request:

{"message_id": "dlq-1234567890", "payload": "{\"fixed\":\"data\"}"}

POST /api/v1/topics/{topic}/schema

Register a validation schema for a topic.

Request:

{"order_id": "string", "amount": "number", "status": "string"}

Messages that fail schema validation are rejected at publish time.

GET /api/v1/topics/{topic}/anomalies

Detect anomalous message patterns (spike detection, schema drift).

GET /api/v1/subscribe/

Subscribe via Server-Sent Events for real-time message consumption.

Response (text/event-stream):

data: {"order_id":"abc-123","amount":99.99}

data: {"order_id":"def-456","amount":45.00}

GET /ws/subscribe/

Subscribe via WebSocket for real-time bidirectional message consumption.

GET /api/v1/tail?topic=

Tail the latest N messages from a topic (useful for debugging).

Query Parameters:

GET /api/v1/stats

Broker statistics and metrics.

Response (200):

{
  "messages_published": 152340,
  "wasm_executions": 45000,
  "wasm_execution_errors": 12,
  "wasm_avg_duration_ns": 250000,
  "topics_count": 8,
  "wal_entries": 152340
}

GET /api/v1/stats/ws

WebSocket endpoint streaming real-time broker stats every second.

POST /api/v1/replay

Replay messages from a specific offset for a consumer group.

Request:

{
  "topic": "orders.created",
  "start_offset": 100,
  "group_name": "analytics-group"
}

Response (200):

{"replayed": 52}

POST /api/v1/replay/time

Seek to a timestamp-based offset.

Request:

{"topic": "orders.created", "timestamp": 1706000000000}

Response (200):

{"offset": 1523}

GET /api/v1/offsets

Get committed offsets for a consumer group.

POST /api/v1/offsets

Commit an offset for a consumer group.

Request:

{"group": "analytics", "topic": "orders.created", "offset": 1523}

GET /api/v1/consumers/lag

Get consumer group lag (difference between latest offset and committed offset).

POST /api/v1/topics/retention

Configure topic retention policy.

POST /api/v1/admin/offloader

Configure tiered storage offloader.

Request:

{
  "s3_endpoint": "http://vault:9000",
  "s3_bucket": "pulse-cold-storage",
  "s3_token": "auth-token"
}

GET /metrics

Prometheus-compatible metrics.

# HELP pranor_pulse_messages_published_total Total messages published
# TYPE pranor_pulse_messages_published_total counter
pranor_pulse_messages_published_total 152340

# HELP pranor_pulse_wasm_executions_total Total WASM transform executions
# TYPE pranor_pulse_wasm_executions_total counter
pranor_pulse_wasm_executions_total 45000

GET /api/v1/events/

Event sourcing API — list events with filtering.

POST /api/v1/sqlite/query

Query broker metadata via embedded SQLite interface.

Messaging Semantics

Publish/Subscribe (Fan-Out)

Every subscriber on a topic receives every message:

Producer → publish("events.user", msg)
  ├── Subscriber-A receives msg
  ├── Subscriber-B receives msg
  └── Subscriber-C receives msg

Consumer Groups (Competing Consumers)

Messages are round-robin dispatched to one member per group:

Producer → publish("orders", msg1)
  Group "processors":
    ├── Worker-1 receives msg1
    ├── Worker-2 receives msg2 (next message)
    └── Worker-3 receives msg3 (next message)

Partitioned Topics

Key-based partitioning ensures ordering per key:

publish("orders", key="customer-A", msg1) → Partition 0
publish("orders", key="customer-A", msg2) → Partition 0 (same key = same partition)
publish("orders", key="customer-B", msg3) → Partition 2 (different key)

Priority Queues

Messages with higher priority are dispatched first regardless of arrival order:

publish("tasks", payload="low", priority=1)
publish("tasks", payload="high", priority=10)
publish("tasks", payload="medium", priority=5)
→ Consumer receives: "high", "medium", "low"

Delayed Messages

Schedule delivery N milliseconds in the future:

publish("reminders", payload="Check order status", delay_ms=300000)
→ Message delivered after 5 minutes

The TimeWheel implementation provides 10ms resolution with O(1) scheduling.

Message Deduplication

Two dedup mechanisms:

1. Message-ID dedup: Same message_id within 5-minute window is dropped
2. Producer-sequence dedup: Per producer_id, any sequence_number ≤ last_seen is dropped

Message TTL / Expiry

Messages with ttl_ms expire and route to the DLQ instead of delivering to consumers:

publish("events", payload="time-sensitive", ttl_ms=5000)
→ If not consumed within 5s, routes to DLQ with reason "message TTL expired"

Topic Compaction

For compacted topics, only the latest message per key is retained:

publish("state", key="user-1", payload="v1")
publish("state", key="user-1", payload="v2")
publish("state", key="user-2", payload="v1")
→ Compacted state: {"user-1": "v2", "user-2": "v1"}

Wildcard Subscriptions

MQTT-style topic patterns:

• * matches exactly one level: sensors.* matches sensors.temp but not sensors.temp.room1
• # matches zero or more levels: events.# matches events, events.user, events.user.login

Dead Letter Queues

When a WASM transform fails, the original message routes to the registered DLQ topic with an envelope containing:

• Original payload
• Source topic
• Failure reason
• Message ID
• Retry count

Protocol Support

STOMP 1.2 (Port 61613)

Full STOMP 1.2 implementation with username/password authentication. Compatible with any STOMP client (ActiveMQ clients, Spring Messaging, etc.).

import stomp
conn = stomp.Connection([('localhost', 61613)])
conn.connect('admin', 'secret', wait=True)
conn.subscribe('/topic/orders', id=1)
conn.send('/topic/orders', '{"order":"123"}')

Kafka Wire Protocol (Port 9092)

Native Kafka producer/consumer compatibility. Existing Kafka applications can point to Pulse without code changes.

MQTT v5 (Port 1883)

Full MQTT v5 support for IoT workloads — QoS levels, retained messages, topic aliases, and shared subscriptions.

HTTP REST API (Port 8082)

JSON-based publish/subscribe with SSE and WebSocket real-time delivery.

OPFS Browser Queue

Client-side JavaScript SDK using Origin Private File System for offline message queuing with automatic sync on reconnection.

Storage & Durability

Write-Ahead Log (WAL)

Every published message is appended to the WAL before acknowledgment. The WAL provides:

• Crash recovery — replays unprocessed messages on restart
• Segment rotation — closed segments can be offloaded to cold storage
• Sequential I/O — optimized for throughput

Tiered Storage Offloading

Configure S3-compatible cold storage for WAL segment archival:

export PRANOR_PULSE_S3_ENDPOINT=http://vault:9000
export PRANOR_PULSE_S3_BUCKET=pulse-archive
export PRANOR_PULSE_S3_TOKEN=auth-token

When a WAL segment rotates, it's automatically uploaded to the configured S3 bucket.

Offset Persistence

Consumer group offsets are stored in-memory with WAL backing. Consumers can:

• Commit offsets explicitly via API
• Replay from any historical offset
• Seek to a timestamp-based position

Security

Standalone Mode (API Token)

HTTP endpoints require:

Authorization: Bearer secret-token

STOMP connections authenticate with username/password.

Ecosystem Mode (Full Auth Stack)

When running within the Pranor ecosystem, the full middleware chain activates:

1. OTel Tracing — every request gets a span
2. Rate Limiting — per-client request throttling
3. CORS — cross-origin handling
4. Max Body Size — 10MB limit
5. JWT Auth — validates Bearer tokens
6. Tenant Isolation — topic namespacing (tenant:topic)

Multi-Tenant Isolation

Topics are automatically namespaced with tenant ID. Tenant A cannot see or publish to Tenant B's topics:

Tenant "acme" publishes to "orders" → stored as "acme:orders"
Tenant "acme" listing topics → only sees topics prefixed "acme:"

TLS Encryption

Enable TLS on both STOMP and HTTP listeners:

export TLS_CERT_FILE=/certs/pulse.crt
export TLS_KEY_FILE=/certs/pulse.key

Observability

Prometheus Metrics

OpenTelemetry Tracing

Every publish operation generates an OTel span with:

• messaging.system: pranor-pulse
• messaging.destination: topic name
• messaging.payload_len: payload size
• Child spans for WASM transforms and DLQ routing

Real-time Stats WebSocket

Connect to /api/v1/stats/ws for streaming broker stats (1-second updates).

Embedded Web UI

Access /ui/ on the HTTP port for a management dashboard showing topics, subscribers, DLQ state, and real-time throughput graphs.

Grafana Dashboard

Import the bundled grafana_dashboard.json for a pre-built Pulse monitoring dashboard.

Client Libraries & SDKs

Go

import "github.com/vyuvaraj/pranor/pulse/sdks/go"

client := pulse.NewClient("http://localhost:8082", "secret-token")

// Publish
err := client.Publish("orders.created", `{"order_id":"abc"}`, pulse.WithPriority(5))

// Subscribe
ch, err := client.Subscribe("orders.created")
for msg := range ch {
    fmt.Println("Received:", msg)
}

Python (STOMP)

import stomp

class MyListener(stomp.ConnectionListener):
    def on_message(self, frame):
        print(f"Received: {frame.body}")

conn = stomp.Connection([('localhost', 61613)])
conn.set_listener('', MyListener())
conn.connect('admin', 'secret', wait=True)
conn.subscribe('/topic/orders.created', id=1, ack='auto')
conn.send('/topic/orders.created', '{"order_id":"abc-123"}')

TypeScript (WebSocket)

const ws = new WebSocket('ws://localhost:8082/ws/subscribe/orders.created');
ws.onmessage = (event) => {
  const order = JSON.parse(event.data);
  console.log('New order:', order);
};

cURL

# Publish
curl -X POST http://localhost:8082/api/v1/publish \
  -H "Authorization: Bearer secret-token" \
  -H "Content-Type: application/json" \
  -d '{"topic":"orders.created","payload":"{\"order_id\":\"abc\"}"}'

# List topics
curl http://localhost:8082/api/v1/topics \
  -H "Authorization: Bearer secret-token"

# Register WASM transform
curl -X POST http://localhost:8082/api/v1/topics/orders.created/transform \
  -H "Authorization: Bearer secret-token" \
  --data-binary @enrich.wasm

# Replay from offset
curl -X POST http://localhost:8082/api/v1/replay \
  -H "Authorization: Bearer secret-token" \
  -d '{"topic":"orders.created","start_offset":0,"group_name":"replay-group"}'

Pranor CLI

pranor pulse publish --topic orders.created --payload '{"id":"abc"}'
pranor pulse subscribe --topic orders.created
pranor pulse topics list
pranor pulse dlq list --topic orders.created
pranor pulse dlq requeue --topic orders.created --message-id dlq-123
pranor pulse replay --topic orders.created --offset 0 --group analytics

Enterprise Edition

Operational Runbook

Messages not being delivered

1. Check /api/v1/topics to confirm the topic exists and has subscribers
2. Verify the publisher is authenticated and targeting the correct tenant namespace
3. Check for backpressure — if queue is full, publishes return 503
4. Review WASM transform logs — transform failures route to DLQ silently
5. Check dedup — same message_id within 5 minutes is dropped

DLQ filling up

1. Check /api/v1/topics/{topic}/dlq/summary for failure pattern clusters
2. Review the WASM transform for bugs — most DLQ entries come from transform errors
3. Use /api/v1/topics/{topic}/dlq/triage for AI-suggested remediation
4. Fix the transform, then requeue messages via /api/v1/topics/{topic}/dlq/requeue

High publish latency

1. Check pranor_pulse_wasm_duration_ns — slow transforms add latency
2. Review backpressure limit — increase PRANOR_PULSE_BACKPRESSURE_LIMIT if queue is healthy
3. Check WAL disk I/O — WAL append is synchronous
4. Verify S3 offloader isn't blocking rotation (network issues to cold storage)

Consumer group rebalancing

1. Check subscriber count on the topic — new/removed consumers trigger rebalance
2. Verify consumer heartbeats are active
3. Review offset commits — stale offsets cause replay on rejoin

WAL recovery after crash

On restart, Pulse automatically:

1. Opens the WAL file
2. Recovers all non-expired entries
3. Re-publishes them through the broker engine
4. Resumes normal operation

No manual intervention required.

Tiered storage not offloading

1. Verify S3 endpoint connectivity: curl $PRANOR_PULSE_S3_ENDPOINT/healthz
2. Check S3 credentials and bucket existence
3. WAL segments only offload on rotation — ensure enough write volume to trigger rotation
4. Check broker logs for offloader errors

Versioning & Compatibility

• HTTP API is versioned at /api/v1/
• Legacy /api/ paths continue to work
• STOMP protocol follows STOMP 1.2 specification
• Kafka wire protocol maintains compatibility with Kafka 2.x+ clients
• MQTT follows MQTT v5.0 specification
• WAL format is forward-compatible within major versions

Pranor Vault — S3-Compatible Object Storage

Version: 2.0.0
Module Path: github.com/vyuvaraj/pranor/vault
Default Ports: 9000 (S3 API), 9001 (Admin Console)
License: AGPL-3.0 (OSS) / Enterprise License (EE with Multi-Region Replication, CoW Branching, Envelope Encryption)

Overview

Pranor Vault is a production-grade S3-compatible object storage engine with embedded vector search, time-travel versioning, erasure coding, bucket branching, WASM transform pipelines, tiered cold storage, and a full admin console. It implements the AWS S3 API specification enabling drop-in compatibility with existing S3 clients, SDKs, and tools.

Pranor Vault can run as:

• A standalone daemon (pranor-vaultd) with zero external dependencies
• An integrated module within the Pranor ecosystem with mTLS, RBAC, OTel tracing, and Console visibility
• A Kubernetes-native store via CSI driver and Helm charts
• A distributed cluster with Raft consensus, consistent hashing, and erasure coding

Table of Contents

• Key Features
• Architecture
• Installation & Deployment
• Configuration
• API Reference
• S3 Compatibility
• Storage Engine
• Security
• Observability
• Client Libraries & CLI
• Enterprise Edition
• Operational Runbook

Key Features

Architecture

graph TD
    subgraph API ["S3-Compatible API Layer"]
        S3["S3 REST API :9000"]
        Admin["Admin API :9001"]
        Console["Web Console /ui/"]
    end

    subgraph Auth ["Auth and RBAC"]
        SigV4["AWS Signature V4 Verification"]
        RBAC["Policy-Based Access Control"]
        RateLimit["Per-Tenant Rate Limiter"]
    end

    subgraph Engine ["Object Processing Engine"]
        S3Ops["S3 Operations Engine"]
        Vector["Vector Search HNSW Index"]
        WASMPipe["WASM Transform Pipeline"]
        Federation["Federation Router"]
    end

    subgraph Cluster ["Distributed Cluster Layer"]
        Raft["Raft Consensus Leader Election"]
        HashRing["Consistent Hash Ring Placement"]
        Erasure["Reed-Solomon Erasure Coding"]
        CRR["Cross-Region Replication"]
    end

    subgraph Storage ["Persistence Layer"]
        LocalStore["Content-Addressed Local Store"]
        Versioning["Version Metadata Engine"]
        ColdTier["S3 Cold Storage Tier"]
        WAL["Write-Ahead Log"]
    end

    S3 --> SigV4
    Admin --> SigV4
    Console --> SigV4
    SigV4 --> RBAC
    RBAC --> RateLimit
    RateLimit --> S3Ops
    RateLimit --> Vector
    RateLimit --> WASMPipe
    S3Ops --> Raft
    Raft --> HashRing
    HashRing --> Erasure
    Erasure --> LocalStore
    LocalStore --> Versioning
    LocalStore -.-> ColdTier
    Versioning --> WAL
    Federation -.-> CRR

Object Lifecycle Sequence Flow

sequenceDiagram
    autonumber
    participant Client as S3 Client
    participant Gate as S3 API Gateway
    participant Auth as SigV4 Auth Layer
    participant Engine as S3 Operations Engine
    participant Cluster as Cluster Placement
    participant Store as Storage Engine
    participant Notify as Event Notifier

    Client->>Gate: PUT /bucket/key (Object Upload)
    Gate->>Auth: Verify AWS Signature V4
    Auth-->>Gate: Authenticated (Access Key + Policy)
    Gate->>Engine: Process PutObject Request
    Engine->>Cluster: Determine Placement via Hash Ring
    Cluster->>Store: Write Object Data + Version Metadata
    Store-->>Cluster: Write Committed (ETag Generated)
    Cluster-->>Engine: Placement Confirmed
    Engine->>Notify: Emit s3:ObjectCreated Event
    Notify-->>Engine: Webhook Dispatched
    Engine-->>Gate: 200 OK (ETag, VersionId)
    Gate-->>Client: HTTP 200 with ETag Header

Ecosystem Cross-Module Integration

Pranor Vault serves as the primary data persistence layer across the Pranor platform:

• Pranor Pulse: Receives closed WAL segments offloaded to S3 buckets for cold archive retention. Vault also emits object event notifications to Pulse topics.
• Pranor Auth: Validates JWT tokens and enforces RBAC bucket policies. OIDC and LDAP integration for enterprise environments.
• Pranor Trace: Every S3 operation generates an OTel span with trace context propagation across cluster nodes.
• Pranor Console: Provides bucket management dashboard, storage capacity monitoring, and object browsing UI.
• Pranor Hub: Uses Vault as the backing store for package artifacts (tarballs, WASM modules, metadata).
• Pranor Secret: Fetches encryption keys for server-side object encryption (SSE-KMS mode).

Installation & Deployment

Binary

cd pranor/vault
CGO_ENABLED=0 go build -o pranor-vaultd ./cmd/pranor-vaultd
CGO_ENABLED=0 go build -o pranor-vault ./cmd/pranor-vault
./pranor-vaultd -port :9000 -admin-port :9001

Docker

docker run -p 9000:9000 -p 9001:9001 -v vault-data:/data \
  ghcr.io/vyuvaraj/pranor-vault:latest

Docker Compose

services:
  vault:
    image: ghcr.io/vyuvaraj/pranor-vault:latest
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - vault-data:/data
    environment:
      - AWS_ACCESS_KEY_ID=minioadmin
      - AWS_SECRET_ACCESS_KEY=minioadmin
volumes:
  vault-data:

Kubernetes (Helm)

helm install pranor-vault ./deploy/helm \
  --set storage.size=100Gi \
  --set replication.factor=3 \
  --set erasure.enabled=true

CSI Driver

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: pranor-vault-csi
provisioner: vault.csi.pranor.io
parameters:
  bucket: my-app-data
  endpoint: http://pranor-vault:9000

As Part of Pranor Ecosystem

When running under the Pranor platform, Vault integrates automatically with Auth (JWT/mTLS), Secret (encryption keys), Trace (OTel spans), Pulse (event notifications), and Console (dashboard visibility).

Configuration

JSON Config (config.json)

{
  "addr": ":9000",
  "admin_addr": ":9001",
  "data_dir": "./data",
  "enable_web_admin": true,
  "default_buckets": ["default-bucket"]
}

Environment Variables

CLI Flags

API Reference

S3-Compatible API (Port 9000)

Pranor Vault implements the AWS S3 REST API. All standard S3 clients work without modification.

Authentication: AWS Signature V4 (compatible with aws-cli, boto3, MinIO client).

GET / — List Buckets

<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>pranor-vault-owner</ID>
    <DisplayName>Pranor Vault Admin</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>my-bucket</Name>
      <CreationDate>2026-01-15T10:00:00Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

PUT /{bucket} — Create Bucket

aws s3 mb s3://my-bucket --endpoint-url http://localhost:9000

DELETE /{bucket} — Delete Bucket

aws s3 rb s3://my-bucket --endpoint-url http://localhost:9000

GET /{bucket} — List Objects

Query parameters: prefix, delimiter, max-keys, continuation-token

aws s3 ls s3://my-bucket/ --endpoint-url http://localhost:9000

PUT /{bucket}/{key} — Put Object

aws s3 cp ./file.txt s3://my-bucket/path/file.txt --endpoint-url http://localhost:9000

Response includes ETag and optional x-amz-version-id.

GET /{bucket}/{key} — Get Object

aws s3 cp s3://my-bucket/path/file.txt ./file.txt --endpoint-url http://localhost:9000

Query param ?versionId= retrieves a specific historical version.

DELETE /{bucket}/{key} — Delete Object

Creates a delete marker (versioned) or permanently removes (unversioned).

HEAD /{bucket}/{key} — Head Object

Returns metadata without body (Content-Type, Content-Length, ETag, version headers).

Multipart Upload

For large objects (>5MB recommended):

# Initiate
POST /{bucket}/{key}?uploads

# Upload parts
PUT /{bucket}/{key}?uploadId={id}&partNumber={n}

# Complete
POST /{bucket}/{key}?uploadId={id}

# Abort
DELETE /{bucket}/{key}?uploadId={id}

POST /{bucket}/{key}?select — S3 Select

Query object contents with SQL:

{
  "Expression": "SELECT s.name, s.age FROM S3Object s WHERE s.age > 30",
  "InputSerialization": {"JSON": {"Type": "LINES"}},
  "OutputSerialization": {"JSON": {}}
}

PUT /{bucket}?versioning — Enable Versioning

<VersioningConfiguration>
  <Status>Enabled</Status>
</VersioningConfiguration>

GET /{bucket}?versions — List Object Versions

Returns all versions including delete markers for time-travel access.

PUT /{bucket}/{key}?lock — Object Lock (WORM)

Enable immutable retention on an object.

PUT /{bucket}/{key}?tagging — Object Tagging

<Tagging>
  <TagSet>
    <Tag><Key>environment</Key><Value>production</Value></Tag>
  </TagSet>
</Tagging>

PUT /{bucket}?lifecycle — Bucket Lifecycle Rules

Configure expiration and tier transitions:

<LifecycleConfiguration>
  <Rule>
    <ID>expire-old-logs</ID>
    <Status>Enabled</Status>
    <Expiration><Days>90</Days></Expiration>
    <Filter><Prefix>logs/</Prefix></Filter>
  </Rule>
</LifecycleConfiguration>

PUT /{bucket}?cold-tier — Configure Cold Tier

Set up tiered storage for infrequently accessed objects.

POST /{bucket}?cold-tier&sweep — Run Cold Sweep

Manually trigger cold storage sweep for a bucket.

PUT /{bucket}?notification — Event Notifications

{
  "bucket": "uploads",
  "events": ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"],
  "webhook": "https://myapp.com/hook"
}

PUT /{bucket}?triggers — Bucket Triggers

Configure WASM triggers that execute on object events.

PUT /{bucket}?geo-placement — Geo-Placement Policy

Set geographic data residency requirements per bucket.

POST /{bucket}?pipeline — WASM Pipeline

Execute a WASM transform pipeline on objects in a bucket.

POST /{bucket}/{key}?transform&target-key={output} — WASM Transform

Transform a single object using a registered WASM module.

POST /{bucket}?delete — Batch Delete

Delete multiple objects in a single request:

<Delete>
  <Object><Key>file1.txt</Key></Object>
  <Object><Key>file2.txt</Key></Object>
</Delete>

GET /{bucket}?ask={query} — Conversational Query

Natural language semantic search over bucket contents:

GET /my-bucket?ask=find+all+invoices+from+2024

GET /{bucket}?sql={query} — SQL Metadata Query

Query bucket metadata using SQL syntax.

Admin API (Port 9001)

GET /api/v1/health

{
  "status": "UP",
  "version": "2.0.0",
  "uptime_sec": 3600.5,
  "bucket_count": 5,
  "daemon": "pranor-vaultd"
}

GET /api/v1/buckets

List all bucket names.

["default-bucket", "uploads", "archive"]

POST /api/v1/buckets

Create a bucket.

{"name": "new-bucket"}

POST /api/v1/events/subscribe

Subscribe to bucket event webhooks.

{
  "bucket": "uploads",
  "events": ["s3:ObjectCreated:*"],
  "webhook": "https://myapp.com/hook"
}

GET /ui/

Built-in web console for bucket management, object browsing, and monitoring.

GET /metrics

Prometheus-compatible metrics endpoint.

POST /admin/backup/restore

Trigger a backup restore operation.

POST /admin/federation

Register a federation routing rule.

POST /admin/batch

Create a batch operations job (bulk copy, delete, tag).

GET /admin/batch/

Check batch job status.

POST /console/login

Authenticate to the web console.

POST /console/logout

End console session.

GET /console/session

Validate current console session.

S3 Compatibility

Supported Operations

Compatible Clients

• AWS CLI — aws s3 --endpoint-url http://localhost:9000
• boto3 (Python) — set endpoint_url parameter
• MinIO Client (mc) — mc alias set vault http://localhost:9000 minioadmin minioadmin
• Go AWS SDK — custom endpoint configuration
• s3cmd — configure with Vault endpoint
• rclone — S3-compatible provider

Storage Engine

Local Storage (Default)

Content-addressed object storage on the local filesystem. Objects are stored in a PebbleDB-backed engine with:

• B-tree indexed metadata
• Content-addressable deduplication
• Atomic write guarantees
• Crash-safe recovery

Erasure Coding

Reed-Solomon erasure coding distributes data across cluster nodes:

Default: 2 data shards + 1 parity shard

Any 2 of 3 shards can reconstruct the original object. Configured via:

NewGateway(store, auth, raftNode, clusterMgr, replicationFactor, erasureEnabled, dataShards, parityShards)

Consistent Hash Ring

Objects are placed on cluster nodes using a consistent hash ring. The ring determines:

• Which nodes own a given object (bucket/key hash)
• Replication targets (next N nodes on ring)
• Request routing (proxy to owner if not local)

Raft Consensus

Leader election and log replication for strong consistency of bucket-level operations (create, delete, versioning config).

Time-Travel Versioning

When versioning is enabled, every PUT creates a new version. Previous versions remain accessible by versionId:

PUT /bucket/key → version v1
PUT /bucket/key → version v2 (v1 still accessible)
DELETE /bucket/key → delete marker (v1, v2 still accessible)
GET /bucket/key?versionId=v1 → returns original content

Cold Storage Tiering

Lifecycle rules automatically move infrequently accessed objects to a cold storage tier:

Hot tier (SSD/local) → 30 days → Cold tier (S3-compatible remote)

Security

AWS Signature V4 Authentication

Standard S3 authentication using access key / secret key pairs:

export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin

RBAC Authorization

Role-based access control with per-bucket and per-action policies. Evaluated after authentication.

Rate Limiting

Per-tenant token-bucket rate limiting:

X-Pranor-Vault-Namespace: tenant-a
→ Rate limited independently per tenant
→ 429 Too Many Requests with Retry-After header on exhaustion

Object Lock (WORM)

Immutable object retention for regulatory compliance:

• Governance mode — privileged users can override
• Compliance mode — no one can delete until retention expires
• Legal hold — indefinite immutability flag

Access Audit Logging

Every S3 operation is logged to the system-access-logs bucket:

{
  "request_id": "trace-id-abc",
  "timestamp": "2026-01-15T10:00:00Z",
  "requester": "admin",
  "bucket": "uploads",
  "key": "data/file.csv",
  "operation": "GET",
  "source_ip": "10.0.1.5:54321",
  "status": 200
}

TLS / mTLS

Configure TLS for the S3 API endpoint. In ecosystem mode, mTLS is available for service-to-service communication.

Console Authentication

The web admin console has its own session-based login separate from S3 credentials.

Observability

Prometheus Metrics

OpenTelemetry Tracing

Every S3 operation generates an OTel span with:

• http.method, http.route, http.status_code
• Trace ID propagation via traceparent header
• Child spans for cluster operations, erasure coding, WASM transforms

Structured JSON Logging

All requests are logged with structured fields:

{
  "level": "INFO",
  "msg": "Request completed",
  "method": "PUT",
  "path": "/uploads/file.txt",
  "status": 200,
  "duration": "12.3ms",
  "trace_id": "abc123"
}

Web Console Dashboard

Access /ui/ on the admin port for real-time monitoring:

• Bucket list with object counts
• Upload/download throughput
• Cluster node health
• Storage capacity utilization

Client Libraries & CLI

AWS CLI

# Configure
aws configure
# Access Key: minioadmin
# Secret Key: minioadmin
# Region: us-east-1

# Create bucket
aws s3 mb s3://my-bucket --endpoint-url http://localhost:9000

# Upload
aws s3 cp ./data.csv s3://my-bucket/data/file.csv --endpoint-url http://localhost:9000

# Download
aws s3 cp s3://my-bucket/data/file.csv ./local.csv --endpoint-url http://localhost:9000

# List
aws s3 ls s3://my-bucket/ --endpoint-url http://localhost:9000

# Delete
aws s3 rm s3://my-bucket/data/file.csv --endpoint-url http://localhost:9000

# Sync directory
aws s3 sync ./local-dir s3://my-bucket/backup/ --endpoint-url http://localhost:9000

MinIO Client (mc)

mc alias set vault http://localhost:9000 minioadmin minioadmin
mc mb vault/my-bucket
mc cp ./file.txt vault/my-bucket/
mc ls vault/my-bucket/
mc cat vault/my-bucket/file.txt

Python (boto3)

import boto3

s3 = boto3.client('s3',
    endpoint_url='http://localhost:9000',
    aws_access_key_id='minioadmin',
    aws_secret_access_key='minioadmin'
)

# Create bucket
s3.create_bucket(Bucket='my-bucket')

# Upload
s3.put_object(Bucket='my-bucket', Key='data/file.json', Body=b'{"hello":"world"}')

# Download
response = s3.get_object(Bucket='my-bucket', Key='data/file.json')
content = response['Body'].read()

# List objects
response = s3.list_objects_v2(Bucket='my-bucket', Prefix='data/')
for obj in response.get('Contents', []):
    print(obj['Key'], obj['Size'])

# Vector search
response = s3.select_object_content(
    Bucket='my-bucket',
    Key='embeddings.jsonl',
    Expression="SELECT * FROM S3Object WHERE similarity > 0.8",
    ExpressionType='SQL',
    InputSerialization={'JSON': {'Type': 'LINES'}},
    OutputSerialization={'JSON': {}}
)

Go

import (
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

cfg, _ := config.LoadDefaultConfig(context.TODO(),
    config.WithEndpointResolver(aws.EndpointResolverFunc(
        func(service, region string) (aws.Endpoint, error) {
            return aws.Endpoint{URL: "http://localhost:9000"}, nil
        },
    )),
)

client := s3.NewFromConfig(cfg)
_, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("data/file.txt"),
    Body:   strings.NewReader("hello world"),
})

Pranor CLI

pranor vault buckets list
pranor vault buckets create my-bucket
pranor vault upload ./file.txt my-bucket/path/file.txt
pranor vault download my-bucket/path/file.txt ./local.txt
pranor vault ls my-bucket/path/
pranor vault bench --bucket test-bucket --objects 10000
pranor vault import --source s3://existing/data --target local-bucket
pranor vault serve-static --bucket my-site --port 3000

cURL (Direct S3 API)

# List buckets (requires proper AWS Sig V4 — simplified with mc or aws-cli)
curl http://localhost:9000/ \
  -H "Authorization: AWS4-HMAC-SHA256 ..."

# Health check (no auth required)
curl http://localhost:9000/healthz

Enterprise Edition

Operational Runbook

Object not found (404)

1. Verify bucket exists: aws s3 ls --endpoint-url http://localhost:9000
2. Check if object was deleted — list versions: GET /bucket?versions
3. If versioned, retrieve by version ID: GET /bucket/key?versionId=v1
4. Check federation rules — object may be on a remote cluster

Upload failing (403 Access Denied)

1. Verify credentials: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
2. Check RBAC policy allows the operation on this bucket
3. Verify AWS Signature V4 is correctly computed (clock skew can cause failures)
4. Check rate limiting — 429 means tenant budget exhausted

Cluster node offline

1. Check /metrics for cluster health indicators
2. Erasure coding tolerates parityShards node failures — data remains accessible
3. The consistent hash ring automatically routes to surviving owners
4. New writes target remaining healthy nodes
5. When the node recovers, rebalancing syncs missed data

High latency on large objects

1. Use multipart upload for objects > 5MB
2. Check erasure coding overhead — encoding adds CPU time
3. Verify cold tier sweep isn't running (blocks I/O during sweep)
4. Review OTel traces for bottleneck identification

Storage capacity approaching limit

1. Review lifecycle rules — ensure expiration is configured
2. Run cold tier sweep: POST /bucket?cold-tier&sweep
3. Check for orphaned multipart uploads: list and abort incomplete uploads
4. Review object versioning — old versions consume space

Bucket deletion failing

1. Bucket must be empty before deletion
2. Use batch delete to remove all objects first
3. Check for object lock (WORM) — locked objects cannot be deleted
4. Verify no active multipart uploads on the bucket

Federation routing not working

1. Check registered federation rules: GET /admin/federation
2. Verify remote cluster is reachable from this node
3. Pattern matching is prefix-based — verify bucket name matches rule
4. Check auth credentials for cross-cluster communication

Console login issues

1. Console auth is separate from S3 credentials
2. Check session cookie validity
3. Verify admin port (9001) is accessible
4. Review console session endpoint: GET /console/session

Versioning & Compatibility

• S3 API follows AWS S3 specification (2006-03-01 namespace)
• Admin API is versioned at /api/v1/
• Storage format is forward-compatible within major versions
• Object data is portable — can be migrated via standard S3 tools
• CSI driver follows CSI spec v1.x
• Helm charts follow Helm 3 conventions

Pranor Chrono — Distributed Job Scheduler

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/chrono
Default Port: 8087
License: AGPL-3.0 (OSS) / Enterprise License (EE with smart scheduling & timezone DSL)

Overview

Pranor Chrono is the distributed, fault-tolerant job scheduling service for the Pranor ecosystem. It supports interval and cron scheduling, exactly-once semantics, DAG job chaining, Pranor cron-as-code declarations, persistent S3 job registries, leader election, retry policies with configurable backoff, and full OTel tracing.

Pranor Chrono can run as:

• A standalone binary with single-node scheduling (no Redis required)
• An integrated module within the Pranor ecosystem with distributed leader election, mTLS, and OTel tracing

Key Features

Architecture

graph TD

    subgraph API ["🌐 Scheduler Control and Cron-as-Code"]
        CronAsCode["Pranor Language .pnr Watcher"]
        JobAPI["REST Scheduler API"]
    end

    subgraph SchedulerCore ["⚡ Distributed Timer and DAG Engine"]
        CronEvaluator["High-Precision Cron Evaluator"]
        LeaderLock["Pranor Lock Fencing Token Leader"]
        DAGRunner["DAG Topological Fan-Out and Join Engine"]
        HTTPDispatcher["HTTP Callback Dispatcher"]
    end

    subgraph History ["💾 Audit Trail and Vault Storage"]
        VaultS3["Pranor Vault S3 Job Registry and Audit Logs"]
        RetryEngine["Exponential Backoff Retry Engine"]
    end

    CronAsCode --> CronEvaluator
    JobAPI --> CronEvaluator
    CronEvaluator --> LeaderLock
    LeaderLock --> DAGRunner
    DAGRunner --> HTTPDispatcher
    HTTPDispatcher --> RetryEngine
    RetryEngine --> VaultS3

High-Precision Distributed Cron Trigger Sequence Flow

sequenceDiagram
    autonumber
    participant Chrono as Pranor Chrono Leader
    participant Lock as Pranor Lock Manager
    participant Service as Target Microservice
    participant Vault as Pranor Vault S3
    participant Trace as Pranor Trace

    Chrono->>Lock: Acquire Job Execution Lease (Key: "cron/cleanup-db")
    Lock-->>Chrono: Granted (Fencing Token = 2088)
    Note over Chrono: Evaluate Cron Expression & Trigger Sub-ms TimeWheel
    Chrono->>Service: POST /tasks/cleanup (Traceparent + Fencing Token)
    Service-->>Chrono: 200 OK (Task Completed in 140ms)
    Chrono->>Vault: Write Audit Execution Log (audit/cleanup-db_20260803.json)
    Chrono->>Trace: Emit OTel Span with Job Execution Metrics
    Chrono->>Lock: Release Job Lease (Token = 2088)

Ecosystem Cross-Module Integration

Pranor Chrono manages high-precision job scheduling across all platform services:

• Pranor Lock: Uses exclusive fencing token leases to guarantee job callbacks execute on exactly one node during multi-replica deployments.
• Pranor Vault: Persists serialized jobs.json configurations and append-only execution audit logs.
• Pranor Flow: Triggers scheduled workflow sagas and periodic maintenance DAGs.
• Pranor Trace: Emits OpenTelemetry trace spans with traceparent context headers for every dispatched cron job.

Installation & Deployment

Binary

cd pranor/chrono
go build -o pranor-chrono .
./pranor-chrono --addr :8087

Docker

docker run -p 8087:8087 ghcr.io/vyuvaraj/pranor-chrono:latest

With Redis Leader Election

./pranor-chrono --addr :8087 --redis-url redis://localhost:6379

As Part of Pranor Ecosystem

When running under the Pranor platform, Chrono integrates automatically with Lock (leader election), Vault (persistence), Trace (OTel spans), and Console (dashboard visibility).

Configuration

Environment Variables

YAML Config (chrono.yaml)

port: "8087"
redis_url: "redis://localhost:6379"
redis_lock_key: "pranor-chrono:leader:lock"
redis_lease_duration: "15s"
vault_url: "http://pranor-vault:7070"
vault_bucket: "pranor-chrono-jobs"
otel_endpoint: "http://pranor-trace:8090"
pnr_files_dir: "./jobs"

CLI Flags

API Reference

Base URL: http://localhost:8087
API Version: /api/v1/ (recommended) or /api/ (legacy)

POST /api/v1/jobs

Create a scheduled job.

Request:

{
  "name": "health-check",
  "schedule": "30s",
  "callback_url": "http://myapp/health",
  "retry": {
    "max": 3,
    "backoff": "exponential"
  }
}

Response (201):

{
  "id": "job-abc-123",
  "name": "health-check",
  "schedule": "30s",
  "status": "active",
  "next_run": "2026-08-01T10:00:30Z"
}

GET /api/v1/jobs

List all jobs.

Response (200):

{
  "jobs": [
    {
      "id": "job-abc-123",
      "name": "health-check",
      "schedule": "30s",
      "status": "active",
      "last_run": "2026-08-01T10:00:00Z",
      "next_run": "2026-08-01T10:00:30Z"
    }
  ]
}

POST /api/v1/jobs/{id}/run

Trigger a job manually (ignores schedule).

Response (200):

{
  "status": "triggered",
  "execution_id": "exec-xyz-789"
}

POST /api/v1/dag

Define a DAG job chain.

Request:

{
  "name": "nightly-pipeline",
  "schedule": "0 2 * * *",
  "steps": [
    { "id": "extract", "callback_url": "http://etl/extract", "depends_on": [] },
    { "id": "transform", "callback_url": "http://etl/transform", "depends_on": ["extract"] },
    { "id": "load", "callback_url": "http://etl/load", "depends_on": ["transform"] }
  ]
}

Response (201):

{
  "id": "dag-001",
  "name": "nightly-pipeline",
  "status": "active",
  "step_count": 3
}

GET /api/v1/jobs/{id}/history

Execution history for a job.

Response (200):

{
  "executions": [
    {
      "id": "exec-001",
      "started_at": "2026-08-01T10:00:00Z",
      "duration_ms": 140,
      "status": "success",
      "http_status": 200
    }
  ]
}

GET /healthz

Liveness probe.

{"status":"UP","service":"pranor-chrono","version":"1.0.0"}

Security

Standalone Mode

In standalone mode, Pranor Chrono runs with single-node scheduling and no Redis dependency. No authentication is required.

Ecosystem Mode (Full Auth Stack)

When running within the Pranor ecosystem, the full middleware chain activates:

1. OTel Tracing — every request gets a span
2. Rate Limiting — per-client request throttling
3. CORS — cross-origin request handling
4. Max Body Size — 10MB request body limit
5. JWT Auth — validates Bearer tokens against Pranor Auth
6. Tenant Isolation — multi-tenant namespace enforcement

Job Callback Security

Job callbacks include:

• traceparent header for distributed tracing
• Fencing token from Pranor Lock leader lease
• Optional bearer token for authenticated callbacks

Observability

Prometheus Metrics

OpenTelemetry Tracing

Every job execution generates OTel spans:

• chrono.schedule.evaluate — cron expression evaluation
• chrono.job.dispatch — HTTP callback dispatch
• chrono.job.retry — retry attempt
• chrono.leader.acquire — leader lease acquisition

Logging

Structured JSON logs with fields: level, timestamp, trace_id, job_id, execution_id, status, duration_ms.

Enterprise Edition

Operational Runbook

Jobs not firing

1. Check leader election — only the leader fires jobs. Verify Redis connectivity
2. Review /api/v1/jobs to confirm job status is active
3. Check pranor_chrono_leader_elections_total metric for frequent re-elections
4. Verify callback URLs are reachable from the Chrono node
5. Check REDIS_LEASE_DURATION isn't too short causing leader thrashing

DAG steps stuck in pending

1. Check /api/v1/dag/{id} for step dependency resolution status
2. Verify upstream step completed successfully (check execution history)
3. Look for circular dependencies in step definitions
4. Check if step callback URL is timing out

High retry rate

1. Monitor pranor_chrono_retries_total metric by job name
2. Check callback service health and response times
3. Review backoff strategy — exponential with jitter prevents thundering herds
4. Consider increasing timeout for slow callbacks
5. Jobs exhausting retries move to DLQ — check DLQ depth

Leader election instability

1. Monitor Redis connectivity and latency
2. Check REDIS_LEASE_DURATION (default 15s) — too short causes flapping
3. Verify clock synchronization between Chrono nodes
4. Check network partitions between nodes and Redis

Pranor Auth — Identity & Access Management

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/auth
Default Port: 8098
License: AGPL-3.0 (OSS) / Enterprise License (EE with Adaptive MFA & Federation)

Overview

Pranor Auth is the centralized authentication, authorization, and identity management service for the Pranor ecosystem. It provides OAuth2/OIDC provider functionality, WebAuthn/FIDO2 passkey login, adaptive multi-factor authentication, JWT issuance with automatic key rotation, RBAC/ABAC policy enforcement, session management, and SCIM provisioning.

Pranor Auth can run as:

• A standalone binary with local user store and JWT signing
• An integrated module within the Pranor ecosystem with mTLS, OTel tracing, tenant isolation, and federated IdP support

Key Features

Architecture

graph TD

    subgraph Clients ["🌐 Auth Ceremony Clients"]
        PasskeyClient["WebAuthn FIDO2 Passkey"]
        MFAClient["TOTP / SMS / Email OTP"]
        OIDCClient["OAuth2 / OIDC Client (PKCE)"]
    end

    subgraph Core ["⚡ Core Identity Engine"]
        SessionMgr["Session Manager and Rotation Engine"]
        AdaptiveMFA["Adaptive Risk-Based Step-Up MFA"]
        JWTProvider["JWT / OIDC Issuer (RS256 / JWKS)"]
        RBACEngine["Granular RBAC / ABAC Policy Engine"]
        SPIFFEExchange["SPIFFE/SPIRE SVID Token Exchanger"]
    end

    subgraph IdentityStores ["💾 Enterprise Identity Provider Federation"]
        FederatedIdP["IdP Mapper (Okta / Azure AD SAML)"]
        UserStore["User Credential Store"]
    end

    PasskeyClient --> SessionMgr
    MFAClient --> AdaptiveMFA
    OIDCClient --> JWTProvider
    SessionMgr --> UserStore
    AdaptiveMFA --> UserStore
    JWTProvider --> RBACEngine
    FederatedIdP --> SPIFFEExchange

Workload Identity Exchange & Authentication Sequence Flow

sequenceDiagram
    autonumber
    participant App as Client / Service Workload
    participant Gate as Pranor Gate Ingress
    participant Auth as Pranor Auth Engine
    participant IdP as Okta / Azure AD (SAML)
    participant SPIFFE as SPIFFE/SPIRE Issuer

    App->>Auth: POST /api/v1/auth/login (Passkey / OAuth2 PKCE)
    Auth->>IdP: Federated Identity Claim Exchange (SAML 2.0)
    IdP-->>Auth: SAML Assertion (User Roles & Group Claims)
    Auth->>SPIFFE: Issue Short-Lived x509 SVID Certificate
    SPIFFE-->>Auth: Signed SVID Workload Identity
    Auth-->>App: RS256 Signed JWT + SPIFFE SVID Certificate
    App->>Gate: Access API (JWT Header + SVID mTLS)
    Gate->>Auth: Introspect Token & Verify RBAC Claims
    Auth-->>Gate: Token Validated & Permissions Granted

Ecosystem Cross-Module Integration

Pranor Auth establishes zero-trust identity across all platform components:

• Pranor Gate: Enforces route-level JWT signature checks, SAML attribute mapping, and SPIFFE/SPIRE workload authentication.
• Pranor Secret: Uses authenticated user identities to authorize access to encrypted vault keys and environment secret maps.
• Pranor Notify: Triggers multi-factor authentication (MFA) Email/SMS one-time passcodes during step-up login ceremonies.
• Pranor Console: Managed via Auth RBAC roles, granting workspace administrators granular cluster control plane privileges.

Installation & Deployment

Binary

cd pranor/auth
go build -o pranor-auth .
./pranor-auth --port 8098

Docker

docker run -p 8098:8098 ghcr.io/vyuvaraj/pranor-auth:latest

As Part of Pranor Ecosystem

When running under the Pranor platform, Auth integrates automatically with Gate (JWT enforcement), Trace (OTel spans), Secret (key storage), and Console (dashboard visibility).

Configuration

Environment Variables

YAML Config (auth.yaml)

port: "8098"
jwt_algorithm: "RS256"
jwt_key_path: "/keys/auth-signing.pem"
session_secret: "32-byte-random-secret-here"
mfa_totp_issuer: "Pranor"
notify_url: "http://pranor-notify:8094"
otel_endpoint: "http://pranor-trace:8090"

CLI Flags

API Reference

Base URL: http://localhost:8098
API Version: /api/v1/ (recommended) or /api/ (legacy)

POST /api/auth/register

Register a new user.

Request:

{
  "username": "alice",
  "password": "secure-password-123",
  "email": "alice@example.com"
}

Response (201):

{
  "status": "success",
  "user_id": "usr-abc-123",
  "message": "User registered successfully"
}

POST /api/auth/login

Authenticate a user and receive a JWT.

Request:

{
  "username": "alice",
  "password": "secure-password-123"
}

Response (200):

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_at": "2026-08-01T11:00:00Z",
  "user_id": "usr-abc-123"
}

POST /api/auth/passkey/register/challenge

Begin WebAuthn passkey registration ceremony.

Request:

{
  "user_id": "usr-abc-123"
}

Response (200):

{
  "challenge": "base64-encoded-challenge",
  "rp": { "name": "Pranor", "id": "pranor.net" },
  "user": { "id": "usr-abc-123", "name": "alice" }
}

POST /api/auth/passkey/login/challenge

Begin WebAuthn authentication ceremony.

Request:

{
  "username": "alice"
}

Response (200):

{
  "challenge": "base64-encoded-challenge",
  "allowCredentials": [{ "id": "cred-xyz", "type": "public-key" }]
}

POST /api/auth/mfa/setup

Set up MFA for a user (TOTP, SMS, or Email).

Request:

{
  "user_id": "usr-abc-123",
  "method": "totp"
}

Response (200):

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code_url": "otpauth://totp/Pranor:alice?secret=JBSWY3DPEHPK3PXP&issuer=Pranor"
}

POST /api/auth/mfa/step-up

Request adaptive MFA step-up based on risk signals.

Request:

{
  "user_id": "usr-abc-123",
  "context": {
    "ip": "203.0.113.42",
    "device_fingerprint": "fp-new-device",
    "action": "high-value-transfer"
  }
}

Response (200):

{
  "step_up_required": true,
  "risk_score": 78,
  "required_factors": ["totp"],
  "reason": "new_device_detected"
}

GET /.well-known/jwks.json

JSON Web Key Set for token verification.

Response (200):

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-2026-08",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

POST /api/auth/sessions/revoke

Invalidate all sessions for a user.

Request:

{
  "user_id": "usr-abc-123"
}

Response (200):

{
  "status": "success",
  "revoked_count": 3
}

GET /healthz

Liveness probe.

{"status":"ok"}

Security

Standalone Mode

In standalone mode, Pranor Auth uses a local user store with bcrypt-hashed passwords and issues self-signed JWTs. Configure PRANOR_AUTH_SESSION_SECRET for session signing.

Ecosystem Mode (Full Auth Stack)

When running within the Pranor ecosystem, the full middleware chain activates:

1. OTel Tracing — every request gets a span
2. Rate Limiting — per-client request throttling
3. CORS — cross-origin request handling
4. Max Body Size — 10MB request body limit
5. JWT Auth — validates Bearer tokens
6. Token Revocation — checks revocation list
7. Tenant Isolation — multi-tenant namespace enforcement

mTLS / SPIFFE

Enable mutual TLS for service-to-service authentication with SPIFFE SVID certificates. Auth issues short-lived x509 workload identities for zero-trust inter-service communication.

KMS Key Rotation

Background KMS envelope key rotation runs on a configurable schedule (default: 24h). JWKS endpoints serve both current and previous keys during rollover for zero-downtime rotation.

Observability

Prometheus Metrics

OpenTelemetry Tracing

Every authentication flow generates OTel spans:

• auth.login — full login ceremony
• auth.mfa.verify — MFA verification step
• auth.token.issue — JWT generation
• auth.passkey.ceremony — WebAuthn challenge/response

Logging

Structured JSON logs with fields: level, timestamp, trace_id, user_id, action, ip, risk_score.

Enterprise Edition

Operational Runbook

Users cannot log in

1. Check /healthz endpoint is returning 200
2. Verify JWT signing key is accessible (PRANOR_AUTH_JWT_KEY_PATH)
3. Check logs for auth.login span errors
4. If MFA is failing, verify Pranor Notify connectivity for OTP delivery
5. Check rate limiter isn't blocking legitimate traffic

JWT tokens rejected by downstream services

1. Verify JWKS endpoint (/.well-known/jwks.json) is accessible from downstream services
2. Check if key rotation occurred — downstream services may be caching stale keys
3. Ensure clock skew between Auth and consumer services is < 30 seconds
4. Check token hasn't been explicitly revoked via /api/auth/sessions/revoke

High credential stuffing alerts

1. Monitor pranor_auth_stuffing_blocks_total metric
2. Review blocked IPs in logs
3. Consider enabling adaptive MFA step-up for all logins from flagged IPs
4. Integrate with upstream WAF for IP-level blocking

KMS key rotation failures

1. Check KMS connectivity and credentials
2. Verify rotation interval configuration (PRANOR_AUTH_KMS_ROTATION_INTERVAL)
3. Monitor logs for kms.rotation errors
4. Manual key rotation: POST /api/auth/rotate-keys

Pranor Cache — Distributed Caching Engine

Version: 0.1.0
Module Path: github.com/vyuvaraj/pranor/cache
Default Port: 8086
License: AGPL-3.0 (OSS) / Enterprise License (EE with TLS offload & SIMD vector cache)

Overview

Pranor Cache is a distributed, high-performance caching service for the Pranor ecosystem. It exposes a low-latency REST API backed by pluggable engines (in-memory or Redis) with native support for OpenTelemetry context propagation, read-through/write-behind database synchronization, key pattern invalidation, bloom filter guards, multi-region replication, and a Redis wire protocol adapter.

Pranor Cache can run as:

• A standalone binary with zero external dependencies (in-memory engine)
• An integrated module within the Pranor ecosystem with mTLS, OTel tracing, and multi-region sync

Key Features

Architecture

graph TD

    subgraph Interface ["🌐 Cache Access Protocol"]
        API["REST Cache Engine API"]
        RedisProto["Redis Wire Protocol Adapter"]
    end

    subgraph Core ["⚡ Core Cache Engine"]
        MemGrid["Thread-Safe In-Memory Data Grid"]
        SIMDVector["SIMD AVX-512 Vector Similarity Cache"]
        BloomFilter["Probabilistic Bloom Filter Guard"]
        MultiTenantPool["Multi-Tenant Isolation Memory Pool"]
    end

    subgraph Persistence ["💾 Pluggable Backends and DB Sync"]
        RedisCluster["Redis / Valkey Cluster"]
        ReadThrough["Read-Through and Write-Behind DB Sync"]
        ActiveMirror["Active-Active Multi-Cluster Sync"]
    end

    API --> MemGrid
    RedisProto --> MemGrid
    MemGrid --> SIMDVector
    SIMDVector --> BloomFilter
    BloomFilter --> MultiTenantPool
    MultiTenantPool --> RedisCluster
    MultiTenantPool --> ReadThrough
    MultiTenantPool -.-> ActiveMirror

Read-Through & SIMD Vector Cache Sequence Flow

sequenceDiagram
    autonumber
    participant App as Microservice / LLM Client
    participant Cache as Pranor Cache Engine
    participant SIMD as SIMD AVX-512 Vector Engine
    participant DB as Backend Database / S3 Store

    App->>Cache: GET /api/cache/prompt-embedding (Cosine Distance < 0.05)
    Cache->>SIMD: Search In-Memory Vector Cache via SIMD AVX-512
    alt Cache Hit (Vector Distance Match)
        SIMD-->>Cache: Cached LLM Response Payload
        Cache-->>App: 200 OK (Instant Cache Hit <50µs)
    else Cache Miss
        SIMD-->>Cache: Cache Miss / Entry Expired
        Cache->>DB: Read-Through Fetch from Backend Storage
        DB-->>Cache: Fresh Payload Data
        Cache->>Cache: Asynchronously Populate Cache Entry & Update Bloom Filter
        Cache-->>App: 200 OK (Read-Through Response)
    end

Ecosystem Cross-Module Integration

Pranor Cache provides sub-millisecond data acceleration across all platform components:

• Pranor Gate: Accelerates semantic prompt caching and API response caching for high-frequency ingress routes.
• Pranor Vault: Caches HNSW vector graph nodes and S3 object metadata in memory for sub-5ms query performance.
• Pranor Auth: Stores active user session tokens, OAuth2 authorization grants, and rate-limiting counters.
• Pranor Trace: Exports cache hit/miss ratio metrics, memory pool allocations, and latency exemplars via OpenTelemetry.

Installation & Deployment

Binary

cd pranor/cache
go build -o pranor-cache .
./pranor-cache --port 8086

Docker

docker run -p 8086:8086 ghcr.io/vyuvaraj/pranor-cache:latest

With Redis Backend

./pranor-cache --port 8086 --backend redis --redis-url redis://localhost:6379

As Part of Pranor Ecosystem

When running under the Pranor platform, Cache integrates automatically with Auth (JWT/mTLS), Trace (OTel spans), and Console (dashboard visibility).

Configuration

Environment Variables

YAML Config (cache.yaml)

port: "8086"
backend: "memory"          # "memory" or "redis"
redis_url: "redis://localhost:6379"
backend_db: ""             # read-through DB endpoint
peers: []                  # peer cache nodes for replication
tls_cert: ""
tls_key: ""

CLI Flags

API Reference

Base URL: http://localhost:8086

POST /api/cache

Set a cache entry.

Request:

{
  "key": "user:101",
  "value": { "name": "Alice", "role": "admin" },
  "ttl": "5m"
}

Response (200):

{
  "status": "success",
  "key": "user:101"
}

GET /api/cache/

Get a cache entry.

Response (200):

{
  "key": "user:101",
  "value": { "name": "Alice", "role": "admin" }
}

Response (404):

{
  "status": "not_found",
  "key": "user:101"
}

DELETE /api/cache/

Delete a specific cache entry.

Response (200):

{
  "status": "deleted",
  "key": "user:101"
}

DELETE /api/cache?pattern=

Invalidate keys by pattern. If no pattern is provided, clears the entire cache.

Response (200):

{
  "status": "success",
  "invalidated": 42
}

GET /health

Health probe showing cache readiness and connection status.

Response (200):

{"status":"UP","service":"pranor-cache","version":"0.1.0","backend":"memory"}

Security

Standalone Mode

In standalone mode, Pranor Cache runs without authentication. Suitable for development and testing.

Ecosystem Mode (Full Auth Stack)

When running within the Pranor ecosystem (detected automatically), the full middleware chain activates:

1. OTel Tracing — every request gets a span
2. Rate Limiting — per-client request throttling
3. CORS — cross-origin request handling
4. Max Body Size — 10MB request body limit
5. JWT Auth — validates Bearer tokens against Pranor Auth
6. Tenant Isolation — multi-tenant namespace enforcement

TLS

Enable HTTPS with TLS certificates:

tls_cert: "/certs/cache.crt"
tls_key: "/certs/cache.key"

TLS offload is an Enterprise feature that uses optimized kernel-bypass SSL termination.

Observability

Prometheus Metrics

OpenTelemetry Tracing

Every cache operation generates OTel spans:

• cache.get — read operation with hit/miss attribute
• cache.set — write operation with TTL
• cache.delete — deletion/invalidation
• cache.read_through — backend fetch on miss

Logging

Structured JSON logs with fields: level, timestamp, trace_id, operation, key, hit, latency_us.

Enterprise Edition

Operational Runbook

High cache miss rate

1. Check /health endpoint for backend connectivity
2. Verify TTLs aren't too short for workload patterns
3. Review bloom filter effectiveness — false positive rate should be < 1%
4. If using read-through, check backend DB latency via pranor_cache_read_through_total
5. Consider increasing memory allocation for the in-memory engine

Replication lag between regions

1. Monitor pranor_cache_replication_lag_ms histogram
2. Check network connectivity to peer nodes (PRANOR_CACHE_PEERS)
3. Verify peer URLs are reachable and responding to health checks
4. Consider reducing write volume if replication can't keep up

Memory pressure / OOM

1. Check pranor_cache_keys_active gauge for key count growth
2. Review TTL policies — ensure all entries have finite TTLs
3. Use pattern invalidation to bulk-remove stale namespaces
4. If using multi-tenant pools, check per-tenant quotas

Redis backend connection failures

1. Verify REDIS_URL is correct and Redis is reachable
2. Check Redis cluster health (CLUSTER INFO)
3. Pranor Cache falls back to in-memory in standalone mode
4. Monitor reconnection attempts in structured logs

Pranor Mesh — Intelligent Service Mesh

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/mesh
Default Port: 8089
License: AGPL-3.0 (OSS) / Enterprise License (EE with WireGuard & mTLS Attestation)

Overview

Pranor Mesh is the intelligent service mesh for the Pranor ecosystem, providing latency-aware Power-of-Two-Choices (P2C) load balancing, distributed rate limiting, live topology telemetry, circuit breaking, mTLS, and chaos fault injection — all without requiring sidecar proxies.

Pranor Mesh can run as:

• A standalone binary providing load balancing and service discovery
• An integrated module within the Pranor ecosystem with distributed rate limiting via Cache, topology push to Console, and mTLS via Auth

Key Features

Architecture

graph TD

    subgraph ServiceTraffic ["🌐 Encrypted Service Connectivity"]
        ClientService["Client Service Pod / Host"]
        mTLSSidecar["mTLS Auto-Inject Sidecar Proxy"]
        WireGuardMesh["WireGuard Private Network Mesh Overlay"]
    end

    subgraph MeshCore ["⚡ Zero-Trust Control and Microsegmentation"]
        P2CRouter["Power-of-Two-Choices (P2C) Load Balancer"]
        Microseg["eBPF Layer 4/7 Microsegmentation Policy Engine"]
        BFTRaft["Byzantine Fault Tolerant (BFT) Raft Control Plane"]
        ChaosEngine["In-Situ Chaos Experiment Injector"]
    end

    subgraph PlatformSync ["💾 Ecosystem Sync and Observability"]
        CacheLimit["Pranor Cache Shared Token Bucket"]
        ConsoleTopology["Pranor Console Live Topology Emitter"]
    end

    ClientService --> mTLSSidecar
    mTLSSidecar --> WireGuardMesh
    WireGuardMesh --> P2CRouter
    P2CRouter --> Microseg
    Microseg --> BFTRaft
    BFTRaft --> ChaosEngine
    ChaosEngine --> CacheLimit
    ChaosEngine -.-> ConsoleTopology

Power-of-Two-Choices (P2C) Routing & Microsegmentation Sequence Flow

sequenceDiagram
    autonumber
    participant Caller as Caller Service A
    participant Mesh as Pranor Mesh Control Plane
    participant eBPF as eBPF Microsegmentation Guard
    participant Backend as Selected Target Service B

    Caller->>Mesh: POST /api/v1/route (Service B, Locality Zone: "us-east-1a")
    Mesh->>eBPF: Validate L4/L7 Zero-Trust Microsegmentation Policy
    eBPF-->>Mesh: Traffic Authorized (Policy Passed)
    Mesh->>Mesh: Pick 2 Random Candidate Endpoints & Evaluate p99 Latency (P2C)
    Mesh->>Backend: Route Mutual TLS Request (WireGuard Overlay)
    Backend-->>Mesh: Response Payload + Health Status
    Mesh-->>Caller: Selected Endpoint Response (Sub-millisecond Latency)

Ecosystem Cross-Module Integration

Pranor Mesh manages secure inter-service communication across all ecosystem components:

• Pranor Gate: Acts as the external ingress target for Mesh WireGuard overlay tunnels and mTLS sidecar proxies.
• Pranor Cache: Shares token bucket rate-limiting counters across all cluster Mesh nodes for global traffic shaping.
• Pranor Auth: Enforces SPIFFE/SPIRE workload identities and mutual TLS (mTLS) certificate verification per service route.
• Pranor Console: Renders live service topology dependency graphs, real-time latency heatmaps, and active chaos experiment controls.

Installation & Deployment

Binary

cd pranor/mesh
go build -o pranor-mesh .
./pranor-mesh --port 8089

Docker

docker run -p 8089:8089 ghcr.io/vyuvaraj/pranor-mesh:latest

With Distributed Rate Limiting

docker run -p 8089:8089 \
  -e PRANOR_MESH_PRANOR_CACHE_URL=http://pranor-cache:8086 \
  -e PRANOR_MESH_PRANOR_CONSOLE_WS_URL=ws://pranor-console:8083/ws/topology \
  ghcr.io/vyuvaraj/pranor-mesh:latest

As Part of Pranor Ecosystem

When running under the Pranor platform, Mesh integrates automatically with Cache (rate limiting), Console (topology), Auth (mTLS), and Trace (OTel spans).

Configuration

Environment Variables

YAML Config (mesh.yaml)

port: "8089"
cache_url: "http://pranor-cache:8086"
console_ws_url: "ws://pranor-console:8083/ws/topology"
locality_zone: "us-east-1a"
otel_endpoint: "http://pranor-trace:8090"
circuit_breaker:
  failure_threshold: 5
  recovery_timeout: "30s"

CLI Flags

API Reference

Base URL: http://localhost:8089

POST /api/v1/services

Register a service endpoint.

Request:

{
  "name": "orders-api",
  "endpoints": ["http://orders-1:3000", "http://orders-2:3000", "http://orders-3:3000"],
  "locality_zone": "us-east-1a"
}

Response (201):

{
  "status": "registered",
  "service": "orders-api",
  "endpoint_count": 3
}

POST /api/v1/route

Route a request via P2C selection.

Request:

{
  "service": "orders-api",
  "caller_zone": "us-east-1a"
}

Response (200):

{
  "selected_endpoint": "http://orders-2:3000",
  "latency_p99_ms": 12,
  "locality_match": true
}

POST /api/v1/ratelimit/policy

Set rate limit policy for a service.

Request:

{
  "service": "orders-api",
  "requests_per_second": 500,
  "burst": 1000
}

Response (200):

{
  "status": "applied",
  "service": "orders-api"
}

POST /api/v1/chaos/inject

Inject a chaos fault.

Request:

{
  "target_service": "payments-api",
  "fault_type": "latency",
  "latency_ms": 200,
  "percentage": 30,
  "duration": "5m"
}

Response (201):

{
  "id": "exp-123",
  "status": "active",
  "expires_at": "2026-08-01T10:05:00Z"
}

GET /api/v1/topology

Current topology graph snapshot.

Response (200):

{
  "services": ["orders-api", "payments-api", "inventory-api"],
  "edges": [
    { "from": "orders-api", "to": "payments-api", "rps": 120, "p99_ms": 45 }
  ]
}

GET /healthz

Liveness probe.

{"status":"UP","service":"pranor-mesh","version":"1.0.0"}

Security

Standalone Mode

In standalone mode, Mesh provides unauthenticated load balancing and service discovery.

Ecosystem Mode (Full Auth Stack)

When running within the Pranor ecosystem:

1. mTLS — mutual TLS for all service-to-service traffic
2. SPIFFE/SPIRE — workload identity attestation per service
3. eBPF Microsegmentation — L4/L7 zero-trust policy enforcement
4. WireGuard Overlay — encrypted mesh network between nodes
5. Token-bucket rate limiting — global enforcement via Pranor Cache

Circuit Breaking

Mesh implements circuit breaking per backend:

• Closed: Normal traffic flow
• Open: All requests fast-fail (after failure threshold)
• Half-Open: Limited probe requests to test recovery

Observability

Prometheus Metrics

OpenTelemetry Tracing

Mesh emits spans for:

• mesh.route — P2C routing decision
• mesh.ratelimit.check — rate limit evaluation
• mesh.chaos.inject — chaos fault injection
• mesh.circuit.trip — circuit breaker state change

Logging

Structured JSON logs with fields: level, timestamp, trace_id, service, endpoint, latency_ms, action.

Enterprise Edition

Operational Runbook

High tail latency on routed requests

1. Check pranor_mesh_backend_latency_ms histogram for p99 spikes
2. Review which backends are being selected — P2C should prefer faster ones
3. Verify locality zone configuration matches actual deployment topology
4. Check if circuit breaker is tripping on slow backends
5. Look for active chaos experiments affecting the target service

Rate limiting blocking legitimate traffic

1. Check pranor_mesh_rate_limit_hits_total for unexpected rejections
2. Review rate limit policy: GET /api/v1/ratelimit/policy
3. Verify Pranor Cache connectivity — rate limit state is shared globally
4. Increase burst allowance if traffic is legitimately spiky

Topology graph missing services

1. Verify services are registered: GET /api/v1/services
2. Check Console WebSocket connectivity (PRANOR_MESH_PRANOR_CONSOLE_WS_URL)
3. Ensure services are actually making calls through Mesh (not direct)
4. Review Mesh logs for registration errors

Chaos experiment not auto-expiring

1. Check experiment status: GET /api/v1/chaos/active
2. Verify system clock is accurate (expiry is time-based)
3. Manually abort: POST /api/v1/chaos/abort/{id}
4. Review duration configuration in the inject request

Pranor Trace — Distributed Tracing & Continuous Profiling

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/trace
Default Port: 8090
License: AGPL-3.0 (OSS) / Enterprise License (EE with AI Anomaly Detection & SIEM Streaming)

Overview

Pranor Trace is the distributed tracing and continuous profiling service for the Pranor ecosystem. It ingests OTLP-format traces, assembles waterfall hierarchies, provides SLO burn rate alerting, delivers eBPF-powered flamegraph profiling with automatic OTel correlation, critical path analysis, and anomaly detection.

Pranor Trace can run as:

• A standalone binary accepting OTLP/HTTP traces with in-memory storage
• An integrated module within the Pranor ecosystem with eBPF profiling, Console integration, and SIEM streaming

Key Features

Architecture

graph TD

    subgraph Ingestion ["🌐 Telemetry Ingestion Layer"]
        OTLP["OTLP / gRPC / HTTP Collector"]
        eBPFProf["Kernel eBPF Continuous Profiler"]
    end

    subgraph Processing ["⚡ Span Reassembly and AI Engine"]
        Reassembly["Span Grouping and Trace ID Linker"]
        CriticalPath["Critical Path Evaluator"]
        AIAutoTune["Autonomous AI Anomaly Auto-Tuner"]
        SLOEngine["SLO Burn Rate Alerting Engine"]
    end

    subgraph Storage ["💾 In-Memory and SIEM Storage"]
        MemStore["In-Memory Evicting Trace Store"]
        SIEMStreamer["Encrypted SIEM Streamer"]
    end

    OTLP --> Reassembly
    eBPFProf --> Reassembly
    Reassembly --> CriticalPath
    CriticalPath --> AIAutoTune
    AIAutoTune --> SLOEngine
    SLOEngine --> MemStore
    MemStore -.-> SIEMStreamer

Telemetry Processing & Flamegraph Correlation Sequence Flow

sequenceDiagram
    autonumber
    participant SDK as Microservice OTLP SDK
    participant Trace as Pranor Trace Collector
    participant eBPF as Kernel eBPF Profiler
    participant AI as AI Anomaly Engine
    participant Console as Pranor Console UI

    SDK->>Trace: POST /v1/traces (Span Tree + TraceID: 0x9918)
    eBPF->>Trace: Push Kernel CPU Stack Samples
    Trace->>Trace: Group Spans by TraceID & Link Parent-Child Tree
    Trace->>AI: Evaluate Span Latency against Baseline
    alt Latency Anomaly Detected
        AI-->>Trace: Raise Burn Rate Alert & Identify Root-Cause Span
        Trace->>Console: Stream Correlated Flamegraph + Log Evidence
    else Standard Trace
        Trace-->>Console: Update Live Waterfall Graph & Dependency Map
    end

Ecosystem Cross-Module Integration

Pranor Trace serves as the central telemetry and observability hub across the Pranor ecosystem:

• Pranor Gate: Ingests W3C traceparent headers, attributing gateway latency and AI prompt token costs to backend trace spans.
• Pranor Flow: Captures individual workflow step execution spans, linking saga compensation steps to root trace IDs.
• Pranor Console: Renders live interactive CPU flamegraphs, distributed service dependency graphs, and SLO burn rate dashboards.
• Pranor Notify: Triggers incident notifications to PagerDuty or Slack when SLO burn rates exceed fast/slow window thresholds.

Installation & Deployment

Binary

cd pranor/trace
go build -o pranor-trace .
./pranor-trace --port 8090

Docker

docker run -p 8090:8090 ghcr.io/vyuvaraj/pranor-trace:latest

With eBPF Profiling

docker run -p 8090:8090 \
  --privileged \
  -e PRANOR_TRACE_EBPF_ENABLED=true \
  -e PRANOR_TRACE_MAX_TRACES=50000 \
  ghcr.io/vyuvaraj/pranor-trace:latest

As Part of Pranor Ecosystem

When running under the Pranor platform, Trace integrates automatically with all services via the PRANOR_OTLP_ENDPOINT env var. Console connects for waterfall rendering and flamegraph display.

Configuration

Environment Variables

YAML Config (trace.yaml)

port: "8090"
max_traces: 50000
ebpf_enabled: true
otel_export: ""
slo_alert_webhook: "http://pranor-notify:8094/api/v1/send"

CLI Flags

API Reference

Base URL: http://localhost:8090

POST /v1/traces

OTLP/HTTP trace ingestion (standard OpenTelemetry endpoint).

Request: Standard OTLP ExportTraceServiceRequest (protobuf or JSON).

Response (200):

{}

GET /api/v1/traces

List recent traces.

Query parameters: service, status, min_duration_ms, limit

Response (200):

{
  "traces": [
    {
      "trace_id": "abc123def456",
      "root_service": "orders-api",
      "root_operation": "POST /orders",
      "duration_ms": 234,
      "span_count": 8,
      "status": "ok",
      "started_at": "2026-08-01T10:00:00Z"
    }
  ]
}

GET /api/v1/traces/

Get full trace with span waterfall hierarchy.

Response (200):

{
  "trace_id": "abc123def456",
  "spans": [
    {
      "span_id": "span-001",
      "parent_span_id": null,
      "service": "orders-api",
      "operation": "POST /orders",
      "duration_ms": 234,
      "status": "ok",
      "children": [
        {
          "span_id": "span-002",
          "service": "payments-api",
          "operation": "charge",
          "duration_ms": 180
        }
      ]
    }
  ]
}

GET /api/v1/traces/{traceID}/critical-path

Critical path analysis for a trace.

Response (200):

{
  "trace_id": "abc123def456",
  "critical_path": [
    { "service": "orders-api", "operation": "POST /orders", "self_time_ms": 54 },
    { "service": "payments-api", "operation": "charge", "self_time_ms": 180 }
  ],
  "bottleneck": "payments-api"
}

POST /api/v1/slo

Define an SLO for a service.

Request:

{
  "service": "orders-api",
  "slo_name": "availability",
  "target_ratio": 0.999,
  "windows": [
    { "name": "fast", "duration": "1h", "burn_rate_threshold": 14.4 },
    { "name": "slow", "duration": "6h", "burn_rate_threshold": 6.0 }
  ]
}

Response (201):

{
  "status": "created",
  "slo_id": "slo-001"
}

GET /api/v1/slo/{service}/burn-rate

SLO burn rate for a service.

Response (200):

{
  "slo": "availability",
  "budget_remaining": 0.82,
  "burn_rate_1h": 2.1,
  "burn_rate_6h": 0.8,
  "alerting": false
}

GET /api/v1/flamegraph/

Latest eBPF flamegraph for a service.

Response (200): SVG or JSON flamegraph data.

GET /healthz

Liveness probe.

{"status":"UP","service":"pranor-trace","version":"1.0.0"}

Security

Standalone Mode

In standalone mode, Trace accepts OTLP spans without authentication. Suitable for development and internal networks.

Ecosystem Mode (Full Auth Stack)

When running within the Pranor ecosystem:

1. JWT Auth — management APIs require Bearer token
2. OTel ingestion — /v1/traces can be optionally auth-gated
3. Tenant Isolation — traces scoped per tenant
4. SIEM Streaming — encrypted export to external SIEM systems
5. Data Retention — configurable max traces with oldest-first eviction

eBPF Security

eBPF profiling requires --privileged Docker flag or CAP_SYS_ADMIN + CAP_BPF capabilities. In production, use a dedicated profiling sidecar with minimal permissions.

Observability

Prometheus Metrics

OpenTelemetry Self-Telemetry

Trace emits its own spans for:

• trace.ingest — span ingestion pipeline
• trace.reassemble — trace ID grouping
• trace.slo.evaluate — burn rate calculation
• trace.flamegraph.correlate — span-to-flamegraph correlation

Logging

Structured JSON logs with fields: level, timestamp, trace_id, service, operation, duration_ms, alert.

Enterprise Edition

Operational Runbook

Traces being evicted too quickly

1. Check pranor_trace_traces_stored gauge vs PRANOR_TRACE_MAX_TRACES
2. Increase PRANOR_TRACE_MAX_TRACES or add more memory
3. Consider exporting to external storage via PRANOR_TRACE_OTEL_EXPORT
4. Review if unnecessary high-cardinality spans are being ingested

SLO alerts firing incorrectly

1. Check pranor_trace_slo_burn_rate metric for the service
2. Verify SLO definition — is the target ratio correct?
3. Review burn rate window configuration (fast: 1h, slow: 6h)
4. Check if a deployment or incident caused a legitimate spike
5. Adjust thresholds if alerting is too sensitive

eBPF profiling not producing data

1. Verify PRANOR_TRACE_EBPF_ENABLED=true
2. Check container has --privileged or necessary capabilities
3. Verify kernel version supports BPF (Linux 4.15+)
4. Check pranor_trace_flamegraph_samples_total metric
5. Review logs for BPF program load errors

High span ingestion latency

1. Monitor span ingestion rate vs processing capacity
2. Check pranor_trace_spans_ingested_total rate
3. If store is full, eviction adds overhead — increase capacity
4. Consider sampling at the SDK level to reduce volume
5. Review if SIEM streaming is creating backpressure

v2.0 OTLP Span Schema (std/trace)

In v2.0, Pranor Trace defines a canonical span name hierarchy and mandatory attributes for all ecosystem modules.

Canonical Span Names

Mandatory Span Attributes

Fault Contract

• Span emission is best-effort and non-blocking (fire-and-forget goroutine)
• Failed writes log a warning to stderr and continue — never on the critical path
• OSS: JSON lines to stderr via stdoutEmitter; EE: full OTLP export to Pranor Trace collector
• Attribute values truncated to 256 bytes per TruncateAttr(v string) string

Pranor Console — Unified Management Dashboard

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/console
Default Port: 8083
License: AGPL-3.0 (OSS) / Enterprise License (EE with AI Co-Pilot & Chaos Panel)

Overview

Pranor Console is the unified, premium management dashboard and observability console for the Pranor ecosystem. It provides a single pane of glass for managing all Pranor components — Gate, Pulse, Vault, Mesh, Deploy, Trace, Flow, and more — with a glassmorphic, real-time UI designed for power users. It features global search, chaos engineering controls, incident management, eBPF flamegraphs, and WebSocket-driven live telemetry.

Pranor Console can run as:

• A standalone binary serving the web UI with manual service URL configuration
• An integrated module within the Pranor ecosystem with auto-discovery, mTLS, and federated telemetry

Key Features

Architecture

graph TD

    subgraph UserInterface ["🌐 Glassmorphic Web and TUI Interface"]
        SPA["React / WASM Glassmorphic SPA"]
        TUI["Terminal TUI Control Plane"]
        WSClient["WebSocket Live Telemetry Stream"]
    end

    subgraph BackendCore ["⚡ Central Control Plane Backend"]
        SearchEngine["Global Ecosystem ⌘K Indexer"]
        ChaosControl["Chaos Experiment Orchestrator"]
        IncidentEngine["Incident Triage and Alert Engine"]
        AIAssistant["Autonomous AI Co-Pilot"]
    end

    subgraph ServiceIntegrations ["💾 Platform Services Monitoring Hub"]
        GateSync["Pranor Gate API Sync"]
        PulseSync["Pranor Pulse Queue and DLQ Sync"]
        VaultSync["Pranor Vault Bucket and Vector Sync"]
        TraceSync["Pranor Trace and eBPF Flamegraph Sync"]
    end

    SPA --> SearchEngine
    TUI --> SearchEngine
    WSClient --> SearchEngine
    SearchEngine --> ChaosControl
    SearchEngine --> IncidentEngine
    SearchEngine --> AIAssistant
    AIAssistant --> GateSync
    AIAssistant --> PulseSync
    AIAssistant --> VaultSync
    AIAssistant --> TraceSync

Real-Time WebSocket Telemetry Stream & Global Search Sequence Flow

sequenceDiagram
    autonumber
    participant Admin as Cluster Operator / Web UI
    participant Console as Pranor Console Backend
    participant Gate as Pranor Gate / Pulse / Vault
    participant Trace as Pranor Trace Engine
    participant AI as Autonomous AI Co-Pilot

    Admin->>Console: Open Console Dashboard & Trigger ⌘K Search ("vector-index-01")
    Console->>Console: Index & Match Cross-Module Resources in Memory
    Console-->>Admin: Display Instant Search Matches (<5ms)
    Console->>Gate: Subscribe to Live WebSocket Metrics Stream (/ws/feeds)
    Gate-->>Console: Stream Throughput, Latency & Error Telemetry
    Console->>Trace: Query High-Burn SLO Spans & eBPF Flamegraphs
    Trace-->>Console: Correlated Flamegraph + Span Waterfall
    Console->>AI: Analyze Cluster Anomaly & Suggest Auto-Remediation
    AI-->>Admin: Render Remediation Action Card in Glassmorphic Panel

Ecosystem Cross-Module Integration

Pranor Console provides single-pane-of-glass management for all platform components:

• Pranor Gate: Inspects dynamic HTTP routes, hot-swaps WASM security modules, and monitors AI token costs.
• Pranor Pulse: Browses topics, tracks consumer group partition lag, and performs 1-click DLQ message triage.
• Pranor Vault: Visualizes HNSW vector graph indexes, browses S3 buckets, and manages CoW bucket branches.
• Pranor Trace: Renders interactive eBPF CPU flamegraphs, distributed service dependency maps, and SLO burn rate dashboards.

Installation & Deployment

Binary

cd pranor/console
go build -o pranor-console .
./pranor-console --port 8083

Docker

docker run -p 8083:8083 ghcr.io/vyuvaraj/pranor-console:latest

With Service Discovery

docker run -p 8083:8083 \
  -e PRANOR_CONSOLE_PRANOR_GATE_URL=http://pranor-gate:8080 \
  -e PRANOR_CONSOLE_PRANOR_PULSE_URL=http://pranor-pulse:9090 \
  -e PRANOR_CONSOLE_PRANOR_VAULT_URL=http://pranor-vault:7070 \
  -e PRANOR_CONSOLE_PRANOR_TRACE_URL=http://pranor-trace:8090 \
  -e PRANOR_CONSOLE_PRANOR_MESH_URL=http://pranor-mesh:8089 \
  ghcr.io/vyuvaraj/pranor-console:latest

As Part of Pranor Ecosystem

When running under the Pranor platform, Console auto-discovers all services via Mesh and displays the full topology.

Configuration

Environment Variables

YAML Config (console.yaml)

port: "8083"
gate_url: "http://pranor-gate:8080"
pulse_url: "http://pranor-pulse:9090"
vault_url: "http://pranor-vault:7070"
trace_url: "http://pranor-trace:8090"
mesh_url: "http://pranor-mesh:8089"
auth_token: "admin-secret-token"
theme: "dark"

CLI Flags

API Reference

Base URL: http://localhost:8083

GET /api/v1/search?q=

Global resource search (⌘K).

Response (200):

{
  "results": [
    { "type": "service", "name": "orders-api", "module": "mesh", "url": "/mesh/services/orders-api" },
    { "type": "route", "name": "/api/orders", "module": "gate", "url": "/gate/routes/api-orders" }
  ],
  "took_ms": 3
}

GET /api/v1/topology/graph

Live service topology graph data.

Response (200):

{
  "nodes": [
    { "id": "orders-api", "type": "service", "status": "healthy" },
    { "id": "payments-api", "type": "service", "status": "degraded" }
  ],
  "edges": [
    { "from": "orders-api", "to": "payments-api", "rps": 120, "error_rate": 0.02, "p99_ms": 45 }
  ]
}

POST /api/v1/chaos/experiments

Create a chaos experiment.

Request:

{
  "name": "latency-spike-test",
  "target_service": "payments-api",
  "fault_type": "latency",
  "latency_ms": 500,
  "percentage": 25,
  "duration": "5m"
}

Response (201):

{
  "id": "exp-001",
  "status": "active",
  "blast_radius": ["orders-api", "checkout-api"],
  "expires_at": "2026-08-01T10:05:00Z"
}

POST /api/v1/incidents

Create an incident.

Request:

{
  "title": "High error rate on payments-api",
  "severity": "P2",
  "services": ["payments-api"],
  "description": "Error rate exceeded 5% SLO threshold"
}

Response (201):

{
  "id": "inc-001",
  "status": "open",
  "created_at": "2026-08-01T10:00:00Z"
}

GET /healthz

Liveness probe.

{"status":"UP","service":"pranor-console","version":"1.0.0"}

Security

Standalone Mode

Set PRANOR_CONSOLE_AUTH_TOKEN for basic token authentication. Clients authenticate via:

Authorization: Bearer admin-secret-token

Ecosystem Mode (Full Auth Stack)

When running within the Pranor ecosystem, Console integrates with Pranor Auth for RBAC-based access control:

1. JWT Auth — validates Bearer tokens against Pranor Auth
2. Role-based dashboard access — admins see all panels; operators see limited views
3. Audit logging — all management actions logged with user identity
4. mTLS — service-to-service communication encrypted

CORS

Console serves the SPA from a configurable origin. CORS headers allow the frontend to call backend APIs cross-origin.

Observability

Prometheus Metrics

OpenTelemetry Tracing

Console emits spans for:

• console.search — global search queries
• console.chaos.inject — chaos experiment triggers
• console.topology.refresh — topology graph rebuilds

Logging

Structured JSON logs with fields: level, timestamp, user_id, action, module, latency_ms.

Enterprise Edition

Operational Runbook

WebSocket connections dropping

1. Check pranor_console_active_sessions gauge for sudden drops
2. Verify network stability between Console and downstream services
3. Check if rate limiting is affecting WebSocket upgrade requests
4. Review nginx/load balancer timeout settings for WebSocket connections
5. Ensure Connection: Upgrade headers are not being stripped

Global search returning stale results

1. Console indexes resources on startup and via WebSocket feeds
2. Force re-index by restarting Console or triggering topology refresh
3. Check connectivity to all configured service URLs
4. Verify Mesh is reporting accurate service catalog

Chaos experiment not propagating

1. Verify Pranor Mesh connectivity (PRANOR_CONSOLE_PRANOR_MESH_URL)
2. Check experiment status via GET /api/v1/chaos/experiments/{id}
3. Confirm target service is registered in Mesh service catalog
4. Review blast radius preview before re-triggering

Dashboard panels blank or loading

1. Check browser console for WebSocket connection errors
2. Verify backend service URLs are correct and accessible
3. Check auth token validity if using static token auth
4. Review CORS configuration if frontend is served from a different origin

Pranor Pool — Database Connection Proxy

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/pool
Default Port: 8097
License: AGPL-3.0 (OSS) / Enterprise License (EE with pgvector accelerator & multi-dialect)

Overview

Pranor Pool is an intelligent, observable database connection pool manager for the Pranor ecosystem. It provides read/write splitting, connection health validation, leak detection, query telemetry, prepared statement caching, pool saturation alerting, and multi-dialect support for PostgreSQL, MySQL, and SQLite.

Pranor Pool can run as:

• A standalone binary providing connection pooling for any PostgreSQL/MySQL application
• An integrated module within the Pranor ecosystem with OTel tracing, Console dashboards, and Lock-coordinated DDL migrations

Key Features

Architecture

graph TD

    subgraph AppCallers ["🌐 Microservice Connection Request"]
        App["Application Microservice Caller"]
        PoolClient["Pranor Pool Go/Python/Java Client"]
    end

    subgraph PoolCore ["⚡ Core Connection Routing and Health Engine"]
        RWRouter["Read/Write Query Router"]
        HealthCheck["Pre-Checkout Validation Engine"]
        LeakDetector["Connection Leak and Goroutine Stack Tracker"]
        StmtCache["Per-Connection Prepared Statement Cache"]
        VectorOffload["PostgreSQL pgvector Accelerator"]
    end

    subgraph DBClusters ["💾 Heterogeneous Relational DB Tier"]
        PrimaryDB["Primary RDBMS"]
        ReplicaPool["Weighted Replica Pool"]
    end

    App --> PoolClient
    PoolClient --> RWRouter
    RWRouter --> HealthCheck
    HealthCheck --> LeakDetector
    LeakDetector --> StmtCache
    StmtCache --> VectorOffload
    VectorOffload --> PrimaryDB
    VectorOffload --> ReplicaPool

Connection Checkout, Read/Write Split & Leak Detection Sequence Flow

sequenceDiagram
    autonumber
    participant App as Application Microservice
    participant Pool as Pranor Pool Manager
    participant Leak as Goroutine Leak Tracker
    participant Stmt as Prepared Statement Cache
    participant DB as Target RDBMS (Primary / Replica)

    App->>Pool: Checkout Connection (Query: "SELECT * FROM users WHERE id = $1")
    Pool->>Pool: Inspect SQL Query Type (Read Query -> Route to Replica Pool)
    Pool->>Leak: Register Goroutine Stack & Start 30s Max-Hold Timer
    Pool->>Stmt: Lookup Cached Prepared Statement ("stmt_users_by_id")
    Stmt-->>Pool: Prepared Statement Handle Ready
    Pool->>DB: Execute Query on Replica DB Instance
    DB-->>Pool: Query Result Set Returned (p99 latency: 1.2ms)
    Pool->>Leak: Cancel Max-Hold Leak Timer & Return Connection to Pool
    Pool-->>App: Connection Released & Stats Updated

Ecosystem Cross-Module Integration

Pranor Pool provides intelligent database proxying across the Pranor ecosystem:

• Pranor Lock: Coordinates zero-downtime online DDL schema migrations, holding exclusive fencing token leases during migrations.
• Pranor Trace: Annotates SQL queries with OpenTelemetry spans, recording query normalization histograms and slow query stack traces.
• Pranor Vault: Connects seamlessly to PostgreSQL pgvector instances, managing connection pools for S3 vector metadata storage.
• Pranor Console: Displays real-time database connection saturation heatmaps, active wait-queue depth, and 1-click connection leak reclaims.

Installation & Deployment

Binary

cd pranor/pool
go build -o pranor-pool .
./pranor-pool --port 8097

Docker

docker run -p 8097:8097 ghcr.io/vyuvaraj/pranor-pool:latest

With OTel and Console

docker run -p 8097:8097 \
  -e PRANOR_POOL_OTEL_ENDPOINT=http://pranor-trace:8090 \
  -e PRANOR_POOL_PRANOR_CONSOLE_URL=http://pranor-console:8083 \
  ghcr.io/vyuvaraj/pranor-pool:latest

As Part of Pranor Ecosystem

When running under the Pranor platform, Pool integrates automatically with Lock (DDL coordination), Trace (query spans), and Console (saturation dashboards).

Configuration

Environment Variables

YAML Config (pool.yaml)

port: "8097"
otel_endpoint: "http://pranor-trace:8090"
console_url: "http://pranor-console:8083"
default_max_connections: 25
leak_check_interval: "30s"
slow_query_threshold_ms: 100

CLI Flags

API Reference

Base URL: http://localhost:8097

POST /api/v1/pools

Create a connection pool.

Request:

{
  "name": "orders-db",
  "primary": "postgres://user:pass@primary:5432/orders",
  "replicas": [
    { "dsn": "postgres://user:pass@replica1:5432/orders", "weight": 70 },
    { "dsn": "postgres://user:pass@replica2:5432/orders", "weight": 30 }
  ],
  "max_connections": 50,
  "min_idle": 5,
  "validation_query": "SELECT 1",
  "max_checkout_duration": "30s",
  "slow_query_threshold_ms": 100
}

Response (201):

{
  "status": "created",
  "name": "orders-db",
  "max_connections": 50
}

GET /api/v1/pools/{name}/stats

Pool stats — utilization, wait queue, active connections.

Response (200):

{
  "name": "orders-db",
  "total": 50,
  "active": 38,
  "idle": 12,
  "wait_queue": 2,
  "utilization_pct": 76
}

GET /api/v1/pools/{name}/leaks

List detected connection leaks.

Response (200):

{
  "leaks": [
    {
      "conn_id": "conn-42",
      "held_since": "2026-08-01T10:00:00Z",
      "duration_s": 45,
      "goroutine": "main.go:84",
      "stack_trace": "goroutine 42 [running]:\nmain.handleOrder(...)"
    }
  ]
}

POST /api/v1/pools/{name}/reclaim

Force-reclaim all leaked connections.

Response (200):

{
  "status": "reclaimed",
  "reclaimed_count": 3
}

GET /api/v1/pools/{name}/query-stats

Per-query latency histograms.

Response (200):

{
  "queries": [
    {
      "signature": "SELECT * FROM orders WHERE id = ?",
      "p50_ms": 3,
      "p75_ms": 8,
      "p90_ms": 22,
      "p99_ms": 45,
      "count": 10234
    }
  ]
}

GET /api/v1/pools/{name}/slow-queries

Recent slow queries.

Response (200):

{
  "queries": [
    {
      "query": "SELECT * FROM orders JOIN items ON ...",
      "duration_ms": 340,
      "timestamp": "2026-08-01T10:01:30Z",
      "caller": "handlers.go:156"
    }
  ]
}

GET /healthz

Liveness probe.

{"status":"UP","service":"pranor-pool","version":"1.0.0"}

Security

Standalone Mode

In standalone mode, Pool provides unauthenticated connection pooling. DSN credentials are stored in memory only.

Ecosystem Mode (Full Auth Stack)

When running within the Pranor ecosystem:

1. JWT Auth — validates Bearer tokens for pool management API
2. Tenant Isolation — pools scoped per tenant namespace
3. OTel Tracing — every query generates a trace span
4. Credential Injection — DSN passwords can be sourced from Pranor Secret

Connection Security

• TLS to database — supports sslmode=require in PostgreSQL DSNs
• Credential rotation — integrates with Pranor Secret for dynamic password rotation
• No credential exposure — DSN passwords never exposed in API responses

Observability

Prometheus Metrics

OpenTelemetry Tracing

Pool emits spans for:

• pool.checkout — connection checkout with routing decision
• pool.query — SQL query execution
• pool.leak.detect — leak detection event
• pool.health.validate — connection validation

Logging

Structured JSON logs with fields: level, timestamp, trace_id, pool, query_signature, duration_ms, connection_id.

Enterprise Edition

Operational Runbook

Pool saturation (high utilization)

1. Check /api/v1/pools/{name}/stats for utilization percentage
2. Monitor pranor_pool_wait_queue_depth — if growing, pool is undersized
3. Increase max_connections in pool configuration
4. Check for connection leaks: GET /api/v1/pools/{name}/leaks
5. Force reclaim leaks: POST /api/v1/pools/{name}/reclaim

Connection leaks accumulating

1. Monitor pranor_pool_leaks_detected_total metric
2. Review leak stack traces: GET /api/v1/pools/{name}/leaks
3. Identify code paths that checkout but don't release connections
4. Reduce max_checkout_duration to catch leaks sooner
5. Ensure all defer conn.Close() patterns are correct in application code

Replica lag causing stale reads

1. Check replica lag via database metrics
2. Configure lag threshold in pool — lagging replicas auto-excluded
3. Monitor how many queries fall back to primary due to lag
4. Consider adding more replicas or optimizing replication

Slow queries increasing

1. Review /api/v1/pools/{name}/slow-queries for patterns
2. Check pranor_pool_query_duration_ms histogram for p99 growth
3. Use query normalization to identify expensive query signatures
4. Work with DBA to add indexes or optimize queries
5. Consider prepared statement cache to reduce parse overhead

Pranor Notify — Multi-Channel Notification Engine

Version: 1.0.0
Module Path: github.com/vyuvaraj/pranor/notify
Default Port: 8094
License: AGPL-3.0 (OSS) / Enterprise License (EE with AI Deliverability & WebPush)

Overview

Pranor Notify is the transactional email, SMS, and push notification service for the Pranor ecosystem. It handles sending, receiving, bounce management, unsubscribe compliance (RFC 8058), DMARC/SPF/DKIM enforcement, inbound email routing, and provides a rich templating DSL with delivery analytics.

Pranor Notify can run as:

• A standalone binary with SMTP relay configuration for email delivery
• An integrated module within the Pranor ecosystem with multi-channel dispatch, OTel tracing, and Console analytics

Key Features

Architecture

graph TD

    subgraph ChannelAdapters ["🌐 Multi-Channel Notification Ingress"]
        EmailAPI["Transactional Email API"]
        PushAPI["WebPush and APNs Provider"]
        SMSAPI["Twilio and Multi-Carrier SMS Gateway"]
    end

    subgraph DispatchEngine ["⚡ Template and Deliverability Engine"]
        TemplateEngine["HTML / DSL Template Rendering Engine"]
        DMARCVal["DMARC / SPF / DKIM Inspector and Alignment"]
        SuppressionList["Automatic Bounce and Suppression Filter"]
        AIOptimizer["AI Deliverability and Send-Time Optimizer"]
    end

    subgraph Relays ["💾 Provider Relays and Analytics"]
        SMTPRelay["Outbound SMTP Relay Pool"]
        WebhookRouter["Inbound Webhook and RFC 8058 Unsubscribe Router"]
    end

    EmailAPI --> TemplateEngine
    PushAPI --> TemplateEngine
    SMSAPI --> TemplateEngine
    TemplateEngine --> DMARCVal
    DMARCVal --> SuppressionList
    SuppressionList --> AIOptimizer
    AIOptimizer --> SMTPRelay
    SMTPRelay --> WebhookRouter

Notification Dispatch & Bounce Suppression Sequence Flow

sequenceDiagram
    autonumber
    participant App as Application Microservice
    participant Notify as Pranor Notify Engine
    participant Suppression as Suppression List
    participant Template as DSL Template Renderer
    participant Gateway as SMTP / SMS / Push Gateway
    participant Analytics as Pranor Console Analytics

    App->>Notify: POST /api/v1/send/template (Template: "welcome-email", User Email)
    Notify->>Suppression: Check Address against Hard-Bounce Suppression List
    Suppression-->>Notify: Clean Record (Not Suppressed)
    Notify->>Template: Inject Payload Variables into DSL Template
    Template-->>Notify: Rendered HTML Body + List-Unsubscribe-Post Header
    Notify->>Gateway: Relay Encrypted Payload via Outbound SMTP / Push Gateway
    Gateway-->>Notify: Delivery Acknowledgment (Message ID: msg-7718)
    Notify->>Analytics: Push Delivery Telemetry & Open/Click Trackers

Ecosystem Cross-Module Integration

Pranor Notify delivers multi-channel communications across the Pranor platform:

• Pranor Auth: Sends one-time password (OTP) codes for multi-factor authentication (MFA) step-up login challenges.
• Pranor Trace: Annotates notification dispatch events with OpenTelemetry traces, recording deliverability latency flamegraphs.
• Pranor Flow: Triggers customer communication steps in saga workflows (e.g., order confirmation emails, shipment SMS alerts).
• Pranor Console: Renders live deliverability analytics, bounce rate histograms, and template editor UI.

Installation & Deployment

Binary

cd pranor/notify
go build -o pranor-notify .
./pranor-notify --port 8094

Docker

docker run -p 8094:8094 ghcr.io/vyuvaraj/pranor-notify:latest