gojinn

package module
v0.29.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 14, 2026 License: Apache-2.0 Imports: 54 Imported by: 0

README

🧞 Gojinn

Go Reference CI Status Build Status Wasm Engine Sponsor

A Sovereign, In-Process Serverless Runtime for Caddy
Execute untrusted code securely with WebAssembly — no containers, no orchestration, no control plane.

Gojinn is a high-performance WebAssembly runtime embedded directly into the Caddy web server.
It allows you to run isolated, deterministic functions inside the HTTP request lifecycle — safely and with near-native performance.


🔑 What Gojinn Is (and Is Not)

✅ Gojinn is
  • A WASM-based serverless runtime
  • Single-binary, self-hosted, and auditable
  • Deterministic, sandboxed, and capability-based
  • Designed for sovereign infrastructure and edge environments
❌ Gojinn is NOT
  • A container orchestrator
  • A Kubernetes replacement
  • A managed cloud service
  • A general-purpose VM or process supervisor

Gojinn executes code and events — not infrastructure.


🚀 Why Gojinn?

Modern serverless stacks suffer from:

  • cold starts
  • idle resource waste
  • infrastructure sprawl
  • opaque control planes
  • vendor lock-in

Gojinn takes a different approach:

  • In-process execution → no network hops, no sidecars
  • Zero idle cost → no requests, no memory usage
  • Strong isolation → every request runs in a fresh WASM sandbox
  • Opinionated design → fewer knobs, more correctness
  • Open & Sovereign → Apache-2.0, self-hosted, auditable

⚡ Performance at a Glance

Metric Docker (Alpine/Go) Gojinn (WASM)
Artifact Size ~20 MB image ~3 MB binary
Execution Model Persistent daemon Ephemeral sandbox
Idle Resource Usage Always-on Zero
Cold Start ~1500ms <1ms

Gojinn prioritizes predictable latency and isolation over long-lived processes.

Detailed benchmarks: docs/benchmark.md


🧠 Core Design Invariant

All user code executes inside a deterministic, isolated, ephemeral WASM sandbox and is never trusted by default.

This invariant is non-negotiable and enforced by governance.
Any feature or contribution that violates it will be rejected.

See: GOVERNANCE.md


🏗 High-Level Architecture

Gojinn runs inside Caddy, not behind it.

sequenceDiagram
    Client->>Caddy: HTTP Request
    Caddy->>Gojinn: Intercept + Context Injection
    Gojinn->>Wazero: Create Sandbox (CPU / Memory limits)
    Wazero->>WASM: JSON via stdin
    WASM->>Wazero: JSON via stdout
    Wazero->>Gojinn: Response
    Gojinn->>Caddy: Stream Response
    Gojinn->>Wazero: Destroy Sandbox

Architecture details: docs/concepts/architecture.md

🛠 Installation

Gojinn is distributed as a Caddy plugin.

xcaddy build \
  --with github.com/pauloappbr/gojinn

⚙️ Configuration (Caddyfile)

{
    order gojinn last
    admin :2019
}

:8080 {
    handle /api/* {
        gojinn ./functions/processor.wasm {
            timeout 2s
            memory_limit 128MB

            env DB_HOST "localhost"
            env API_KEY {env.SECRET_KEY}
        }
    }
}

Full reference: docs/reference/caddyfile.md

🧩 Writing Functions (The Contract)

Gojinn uses a strict JSON protocol over stdin/stdout.

  • stdin → request context (JSON)
  • stdout → response (JSON)
  • stderr → logs only

Language support is polyglot via WASM:

  • Go
  • Rust
  • Zig
  • C / C++
  • Swift (experimental)

Contract definition: docs/concepts/contract.md

📊 Observability

Built-in, no sidecars required:

  • Metrics → Prometheus
  • Tracing → OpenTelemetry
  • Logs → Structured, via Caddy

Metrics endpoint:

http://localhost:2019/metrics

📚 Documentation

  • Getting Started
  • Guides
  • Concepts
  • Use Cases

🧭 Project Direction

  • Roadmap
  • Manifesto
  • Governance

Gojinn is built with long-term correctness, not short-term convenience.

🤝 Community & Support

  • Contributions
  • Support policy
  • Security issues

📄 License

Apache License 2.0
See LICENSE

Documentation

Index

Constants

View Source
const (
	MaxRetries     = 5
	MaxOutputBytes = 5 * 1024 * 1024
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AIMessage added in v0.10.0

type AIMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type AIRequest added in v0.10.0

type AIRequest struct {
	Model    string      `json:"model"`
	Messages []AIMessage `json:"messages"`
	Stream   bool        `json:"stream"`
}

type AIResponse added in v0.10.0

type AIResponse struct {
	Choices []struct {
		Message AIMessage `json:"message"`
	} `json:"choices"`
}

type ConsensusPolicy added in v0.26.0

type ConsensusPolicy struct {
	Namespace  string `json:"namespace"`
	Mode       string `json:"mode"`
	StaleReads bool   `json:"stale_reads"`
}

type CrashSnapshot added in v0.16.0

type CrashSnapshot struct {
	Timestamp time.Time         `json:"timestamp"`
	Error     string            `json:"error"`
	Input     json.RawMessage   `json:"input"`
	Env       map[string]string `json:"env"`
	WasmFile  string            `json:"wasm_file"`
}

type CronJob added in v0.9.0

type CronJob struct {
	Schedule string `json:"schedule"`
	WasmFile string `json:"wasm_file"`
}

type EnginePair added in v0.4.0

type EnginePair struct {
	Runtime wazero.Runtime
	Code    wazero.CompiledModule
}

type FunctionDiscovery added in v0.24.0

type FunctionDiscovery struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	InputSchema string `json:"input_schema"`
}

type Gojinn

type Gojinn struct {
	Path        string            `json:"path,omitempty"`
	Args        []string          `json:"args,omitempty"`
	Env         map[string]string `json:"env,omitempty"`
	Timeout     caddy.Duration    `json:"timeout,omitempty"`
	MemoryLimit string            `json:"memory_limit,omitempty"`
	PoolSize    int               `json:"pool_size,omitempty"`
	DebugSecret string            `json:"debug_secret,omitempty"`

	RecordCrashes bool   `json:"record_crashes,omitempty"`
	CrashPath     string `json:"crash_path,omitempty"`

	DataDir string `json:"data_dir,omitempty"`

	TrustedKeys    []string `json:"trusted_keys,omitempty"`
	SecurityPolicy string   `json:"security_policy,omitempty"`

	NatsPort   int      `json:"nats_port,omitempty"`
	NatsRoutes []string `json:"nats_routes,omitempty"`

	NatsUserSeed     string   `json:"nats_user_seed,omitempty"`
	TrustedNatsUsers []string `json:"trusted_nats_users,omitempty"`

	Perms Permissions `json:"permissions,omitempty"`

	ExposeAsTool bool              `json:"expose_as_tool,omitempty"`
	ToolMeta     FunctionDiscovery `json:"tool_meta,omitempty"`

	FuelLimit uint64            `json:"fuel_limit,omitempty"`
	Mounts    map[string]string `json:"mounts,omitempty"`

	DBDriver string `json:"db_driver,omitempty"`
	DBDSN    string `json:"db_dsn,omitempty"`

	DBSyncURL   string `json:"db_sync_url,omitempty"`
	DBSyncToken string `json:"db_sync_token,omitempty"`

	S3Endpoint  string `json:"s3_endpoint,omitempty"`
	S3Region    string `json:"s3_region,omitempty"`
	S3Bucket    string `json:"s3_bucket,omitempty"`
	S3AccessKey string `json:"s3_access_key,omitempty"`
	S3SecretKey string `json:"s3_secret_key,omitempty"`

	CronJobs []CronJob `json:"cron_jobs,omitempty"`

	MQTTBroker   string    `json:"mqtt_broker,omitempty"`
	MQTTClientID string    `json:"mqtt_client_id,omitempty"`
	MQTTUsername string    `json:"mqtt_username,omitempty"`
	MQTTPassword string    `json:"mqtt_password,omitempty"`
	MQTTSubs     []MQTTSub `json:"mqtt_subs,omitempty"`

	AIProvider string `json:"ai_provider,omitempty"`
	AIModel    string `json:"ai_model,omitempty"`
	AIEndpoint string `json:"ai_endpoint,omitempty"`
	AIToken    string `json:"ai_token,omitempty"`

	APIKeys      []string `json:"api_keys,omitempty"`
	AllowedHosts []string `json:"allowed_hosts,omitempty"`
	CorsOrigins  []string `json:"cors_origins,omitempty"`

	RateLimit float64 `json:"rate_limit,omitempty"`
	RateBurst int     `json:"rate_burst,omitempty"`

	ClusterName  string   `json:"cluster_name,omitempty"`
	ClusterPort  int      `json:"cluster_port,omitempty"`
	ClusterPeers []string `json:"cluster_peers,omitempty"`

	ClusterReplicas int               `json:"cluster_replicas,omitempty"`
	Consensus       []ConsensusPolicy `json:"consensus,omitempty"`

	StoreCipherKey string `json:"store_cipher_key,omitempty"`

	ServerName string `json:"server_name,omitempty"`

	LeafRemotes []string `json:"leaf_remotes,omitempty"`
	LeafPort    int      `json:"leaf_port,omitempty"`
	// contains filtered or unexported fields
}

func (*Gojinn) CaddyModule

func (*Gojinn) CaddyModule() caddy.ModuleInfo

func (*Gojinn) Cleanup

func (r *Gojinn) Cleanup() error

func (*Gojinn) CreateGlobalSnapshot added in v0.27.0

func (r *Gojinn) CreateGlobalSnapshot() (string, error)

func (*Gojinn) EnsureTenantResources added in v0.28.0

func (g *Gojinn) EnsureTenantResources(tenantID string) (nats.KeyValue, error)

func (*Gojinn) EnsureTenantWorkers added in v0.28.0

func (r *Gojinn) EnsureTenantWorkers(tenantID string) error

func (*Gojinn) HandleMCPMessage added in v0.24.0

func (r *Gojinn) HandleMCPMessage(w http.ResponseWriter, req *http.Request)

func (*Gojinn) Provision

func (r *Gojinn) Provision(ctx caddy.Context) error

func (*Gojinn) ReloadWorkers added in v0.18.0

func (g *Gojinn) ReloadWorkers() error

func (*Gojinn) RestoreGlobalSnapshot added in v0.27.0

func (r *Gojinn) RestoreGlobalSnapshot(archivePath string) error

func (*Gojinn) SemanticMatch added in v0.24.0

func (r *Gojinn) SemanticMatch(query string) bool

func (*Gojinn) ServeHTTP

func (r *Gojinn) ServeHTTP(rw http.ResponseWriter, req *http.Request, next caddyhttp.Handler) error

func (*Gojinn) ServeMCP added in v0.24.0

func (r *Gojinn) ServeMCP(w http.ResponseWriter, req *http.Request)

type HttpContext added in v0.15.0

type HttpContext struct {
	W      http.ResponseWriter
	R      *http.Request
	WSConn *websocket.Conn
}

type MQTTSub added in v0.9.0

type MQTTSub struct {
	Topic    string `json:"topic"`
	WasmFile string `json:"wasm_file"`
}

type Permissions added in v0.23.0

type Permissions struct {
	KVRead  []string `json:"kv_read,omitempty"`
	KVWrite []string `json:"kv_write,omitempty"`
	S3Read  []string `json:"s3_read,omitempty"`
	S3Write []string `json:"s3_write,omitempty"`
}

type ToolDefinition added in v0.24.0

type ToolDefinition struct {
	Name        string      `json:"name"`
	Description string      `json:"description"`
	InputSchema interface{} `json:"inputSchema"`
}

Directories

Path Synopsis
cmd
caddy command
gojinn command
signer command
pkg

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL