go

Reglet Go SDK

The Reglet Go SDK provides Go APIs for writing WebAssembly (WASM) plugins for the Reglet compliance platform. It handles memory management, host communication, plugin registration, and provides safe wrappers for network operations, command execution, and logging.

Version

Current Version: 0.1.0-alpha

Features

• Example-Based Testing: Register examples that become documentation and auto-generated tests
• Full Context Propagation: Deadlines, cancellation, and values flow to all operations
• Memory Management: Automatic allocation tracking with 100 MB safety limit
• Network Operations: DNS, HTTP, TCP, and SMTP with explicit API
• Command Execution: Sandboxed command execution via host
• Type-Safe Wire Protocol: JSON-based ABI with validation

Installation

go get github.com/reglet-dev/reglet-sdk/go

Quick Start

Minimal Plugin

package main

import (
	"context"
	"log/slog"

	"github.com/reglet-dev/reglet-sdk/go/application/plugin"
	"github.com/reglet-dev/reglet-sdk/go/application/schema"
	"github.com/reglet-dev/reglet-sdk/go/domain/entities"
)

type MyPlugin struct{}

func main() {
	plugin.Register(&MyPlugin{})
}

func (p *MyPlugin) Describe(ctx context.Context) (entities.Metadata, error) {
	return entities.Metadata{
		Name:         "my-plugin",
		Version:      "1.0.0",
		Description:  "Example compliance check plugin",
		Capabilities: []entities.Capability{
			entities.NewCapability("network:outbound", "example.com:443"),
		},
	}, nil
}

type Config struct {
	Hostname string `json:"hostname" jsonschema:"description=Hostname to check"`
}

func (p *MyPlugin) Schema(ctx context.Context) ([]byte, error) {
	return schema.GenerateSchema(Config{})
}

func (p *MyPlugin) Check(ctx context.Context, configMap map[string]any) (entities.Result, error) {
	// ... config loading ...
	hostname := "example.com"

	slog.InfoContext(ctx, "Starting check", "hostname", hostname)

	// Plugin logic here...

	return entities.ResultSuccess("Check passed", map[string]any{
		"hostname": hostname,
		"status":   "ok",
	}), nil
}

Building

GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o plugin.wasm main.go

Package Documentation

Detailed documentation for each subpackage:

• host - Host runtime execution (WASM engine)
• application/plugin - Plugin development, typed operations (Op[I,O], RegisterOp, GetClient)
• application/schema - JSON Schema generation from Go structs
• exec - Command execution
• log - Structured logging
• net - Network operations (DNS, HTTP, TCP)

Core Concepts

Plugin Interface

Every plugin must implement three methods:

type Plugin interface {
    // Describe returns metadata about the plugin
    Describe(ctx context.Context) (entities.Metadata, error)

    // Schema returns JSON schema for plugin configuration
    Schema(ctx context.Context) ([]byte, error)

    // Check executes the main plugin logic
    Check(ctx context.Context, config map[string]any) (entities.Result, error)
}

Typed Operations (Recommended)

For plugins with multiple operations or complex input/output types, use the typed operations pattern. This provides type safety, auto-generated JSON schemas, and example-based testing.

Defining a Typed Service

package services

import (
    "context"
    "github.com/reglet-dev/reglet-sdk/go/application/plugin"
    "github.com/reglet-dev/reglet-sdk/go/domain/ports"
)

// Input/Output types with JSON schema tags
type ResolveInput struct {
    Hostname   string `json:"hostname" jsonschema:"required,description=Target hostname to resolve"`
    RecordType string `json:"record_type,omitempty" jsonschema:"enum=A,enum=MX,enum=TXT,default=A"`
}

type ResolveOutput struct {
    Hostname string   `json:"hostname" jsonschema:"description=Queried hostname"`
    Records  []string `json:"records" jsonschema:"description=Resolved DNS records"`
}

// Service struct with typed Op fields
type DNSService struct {
    plugin.Service `name:"dns" desc:"DNS resolution and record lookup"`

    Resolve plugin.Op[ResolveInput, ResolveOutput] `desc:"Resolve hostname" method:"ResolveHandler"`
}

func init() {
    // Register operation with examples (used for docs and auto-testing)
    plugin.RegisterOp[ResolveInput, ResolveOutput]("Resolve",
        plugin.Example[ResolveInput, ResolveOutput]{
            Name:        "basic_a",
            Description: "Resolve A record",
            Input:       ResolveInput{Hostname: "example.com", RecordType: "A"},
            ExpectedOutput: &ResolveOutput{
                Hostname: "example.com",
                Records:  []string{"93.184.216.34"},
            },
        },
        plugin.Example[ResolveInput, ResolveOutput]{
            Name:          "nxdomain",
            Description:   "Non-existent domain",
            Input:         ResolveInput{Hostname: "invalid.test"},
            ExpectedError: "DNS lookup failed",
        },
    )

    // Auto-register service with plugin
    plugin.MustRegisterService(core.Plugin, &DNSService{})
}

// Typed handler - receives parsed input, returns typed output
func (s *DNSService) ResolveHandler(ctx context.Context, in *ResolveInput) (*ResolveOutput, error) {
    // Get client from context (injected by runtime)
    resolver := plugin.GetClient[ports.DNSResolver](ctx)

    records, err := resolver.LookupHost(ctx, in.Hostname)
    if err != nil {
        return nil, fmt.Errorf("DNS lookup failed: %w", err)
    }

    return &ResolveOutput{
        Hostname: in.Hostname,
        Records:  records,
    }, nil
}

Benefits

Feature	Description
Type Safety	Handlers receive *Input and return *Output - no manual parsing
Auto Schemas	JSON schemas generated from struct tags for CLI and docs
Example Testing	GenerateExampleTests() creates tests from registered examples
Client Injection	plugin.GetClient[T](ctx) provides type-safe client access
Rich Manifests	Manifest includes input_fields, output_schema, and examples

Client Injection

Access injected clients via context with type safety:

// Get client - panics if wrong type or missing
client := plugin.GetClient[*MyClient](ctx)

// Try to get client - returns nil if missing
client, ok := plugin.TryGetClient[*MyClient](ctx)
if !ok {
    return nil, errors.New("client not injected")
}

Auto-Generated Tests

Use GenerateExampleTests to create tests from registered examples:

package services_test

import (
    "testing"
    "github.com/reglet-dev/reglet-sdk/go/application/plugin"
    "myproject/plugins/dns/core"
)

func TestExamples(t *testing.T) {
    mockClient := &mockDNSResolver{
        records: map[string][]string{
            "example.com": {"93.184.216.34"},
        },
    }
    // Runs all registered examples as subtests
    plugin.GenerateExampleTests(t, core.Plugin, mockClient)
}

Manifest Output

Typed operations generate rich manifests for CLI tooling:

{
  "services": {
    "dns": {
      "operations": [{
        "name": "resolve",
        "description": "Resolve hostname",
        "input_fields": ["hostname", "record_type"],
        "output_schema": {
          "properties": {
            "hostname": {"type": "string"},
            "records": {"type": "array", "items": {"type": "string"}}
          }
        },
        "examples": [
          {"name": "basic_a", "input": {"hostname": "example.com"}}
        ]
      }]
    }
  }
}

Context Propagation

All SDK functions properly propagate Go contexts:

// Timeouts
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
resp, err := net.Get(ctx, url) // Respects 5 second timeout

// Cancellation
ctx, cancel := context.WithCancel(context.Background())
go func() {
    time.Sleep(1 * time.Second)
    cancel() // Cancels the HTTP request
}()
resp, err := net.Get(ctx, url)

// Values (for request tracing)
ctx = context.WithValue(ctx, "request_id", "abc123")
resp, err := net.Get(ctx, url) // request_id passed to host logs

Memory Management

The SDK tracks all memory allocations and enforces a 100 MB limit:

const MaxTotalAllocations = 100 * 1024 * 1024 // 100 MB

If your plugin exceeds this limit, it will panic with:

abi: memory allocation limit exceeded (requested: X bytes, current: Y bytes, limit: 104857600 bytes)

Best Practices:

• Stream large data instead of loading into memory
• Free resources promptly (close HTTP response bodies)
• Avoid caching large datasets in plugin memory

Version Checking

The SDK automatically reports its version in plugin metadata:

metadata, _ := plugin.Describe(ctx)
// metadata.SDKVersion = "0.1.0-alpha"
// metadata.MinHostVersion = "0.2.0"

The host is responsible for validating compatibility:

• If host version < MinHostVersion → reject plugin
• If plugin uses unsupported SDK features → runtime errors

Network Operations

DNS Resolution

Use the WasmResolver for DNS lookups:

import sdknet "github.com/reglet-dev/reglet-sdk/go/net"

resolver := &sdknet.WasmResolver{
    Nameserver: "", // Empty = use host's default
}
ips, err := resolver.LookupHost(ctx, "example.com")

See net/README.md for full DNS API documentation.

HTTP Requests

Option 1 - SDK Helpers (Recommended):

import sdknet "github.com/reglet-dev/reglet-sdk/go/net"

resp, err := sdknet.Get(ctx, "https://example.com")
defer resp.Body.Close()

Option 2 - Custom Client:

import (
    "net/http"
    sdknet "github.com/reglet-dev/reglet-sdk/go/net"
)

client := &http.Client{
    Transport: &sdknet.WasmTransport{},
    Timeout:   10 * time.Second,
}
resp, err := client.Get("https://example.com")

HTTP Body Size Limit

HTTP response bodies are limited to 10 MB (net.MaxHTTPBodySize).

See net/README.md for full HTTP API documentation.

TCP Connections

import (
	sdknet "github.com/reglet-dev/reglet-sdk/go/net"
	"github.com/reglet-dev/reglet-sdk/go/domain/entities"
)

// DialTCP(ctx, host, port, timeoutMs, useTLS)
conn, err := sdknet.DialTCP(ctx, "example.com", "443", 5000, true)
if err != nil {
    return entities.ResultFailure("tcp connection failed", map[string]any{"error": err.Error()}), nil
}

return entities.ResultSuccess("connected", map[string]any{
    "connected":      conn.Connected,
    "tls":            conn.TLS,
    "tls_version":    conn.TLSVersion,
    "response_ms":    conn.ResponseTimeMs,
}), nil

See net/README.md for full TCP API documentation.

Command Execution

Execute host commands via sandboxed interface:

import (
	"github.com/reglet-dev/reglet-sdk/go/exec"
	"github.com/reglet-dev/reglet-sdk/go/domain/entities"
)

req := exec.CommandRequest{
    Command: "systemctl",
    Args:    []string{"is-active", "nginx"},
}

result, err := exec.Run(ctx, req)
if err != nil {
    return entities.ResultFailure("execution error", map[string]any{"error": err.Error()}), nil
}

serviceActive := result.ExitCode == 0

return entities.ResultSuccess("service checked", map[string]any{
    "service": "nginx",
    "active":  serviceActive,
    "stdout":  result.Stdout,
}), nil

See exec/README.md for full exec API documentation.

Structured Logging

Use Go's standard log/slog package:

import (
    "log/slog"
    "github.com/reglet-dev/reglet-sdk/go/domain/entities"
    _ "github.com/reglet-dev/reglet-sdk/go/log" // Initialize WASM logging
)

func (p *MyPlugin) Check(ctx context.Context, config map[string]any) (entities.Result, error) {
    // Context-aware logging (recommended)
    slog.InfoContext(ctx, "Starting check", "config_keys", len(config))

    // Structured attributes
    slog.Debug("Processing item", "item_id", 123, "status", "pending")

    // Error logging
    // ...

    return entities.ResultSuccess("ok", nil), nil
}

See log/README.md for full logging API documentation.

Schema Generation

Generate JSON Schema from Go structs using application/schema:

import "github.com/reglet-dev/reglet-sdk/go/application/schema"

type PluginConfig struct {
    Hostname string `json:"hostname" jsonschema:"description=Target hostname"`
    Port     int    `json:"port" jsonschema:"default=443,description=Target port"`
}

func (p *MyPlugin) Schema(ctx context.Context) ([]byte, error) {
    return schema.GenerateSchema(PluginConfig{})
}

Supported Tags:

• json:"name" - Field name
• jsonschema:"..." - Schema attributes (default, description, etc.)

Error Handling

Use SDK error helpers for consistent error reporting:

// Success
return entities.ResultSuccess("Check passed", map[string]any{
    "result": "ok",
}), nil

// Simple failure
return entities.ResultFailure("Invalid hostname format", nil), nil

// Network error
return entities.ResultError(entities.NewErrorDetail("network", err.Error())), nil

// Configuration error
return entities.ResultError(entities.NewErrorDetail("config", "missing required field")), nil

Capabilities

Plugins must declare their required capabilities. The recommended approach is using a plugin.yaml manifest file, which allows for structured and granular permission control.

Manifest Example (plugin.yaml)

name: my-plugin
version: 1.0.0
capabilities:
  network:
    rules:
      - hosts: ["api.example.com", "*.google.com"]
        ports: ["443", "80-90"]
  fs:
    rules:
      - read: ["/data/**"]
        write: ["/tmp/app.log"]
  env:
    vars: ["AWS_REGION", "DEBUG"]
  exec:
    commands: ["/usr/bin/grep"]
  kv:
    rules:
      - keys: ["config-*"]
        op: "read-write"

Capability Types

• Network: rules array with hosts and ports. Wildcards (*) supported.
• FileSystem: rules array with read and write paths. Recursive access via **.
• Environment: vars array of permitted environment variables.
• Exec: commands array of allowed external commands.
• KeyValue: rules array with keys and op (read, write, or read-write).

Note: Capabilities are granted by the host. The plugin.yaml defines what the plugin requests.

Limitations

Network

• No Streaming: HTTP responses are fully buffered (10 MB limit)
• No WebSockets: Not supported
• TCP Check-Only: Can connect but not perform bidirectional communication
• No UDP: UDP protocol not supported
• No Raw Sockets: Only standard protocols (HTTP, TCP, DNS)

Execution

• Single-Threaded: WASI Preview 1 is single-threaded (use goroutines for logical concurrency)
• No Interactive Commands: Commands requiring stdin will fail
• No Shell Features: Commands executed directly, not through a shell

Filesystem

• Sandboxed Access: Restricted to paths granted by capabilities
• No Direct WASI: Must use host functions, not WASI filesystem directly

Memory

• 100 MB Limit: Total allocations capped at 100 MB
• No Memory Pooling: Each allocation goes through Go's allocator

Best Practices

1. Always Use Context with Timeouts

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

// All operations respect the timeout
resp, err := sdknet.Get(ctx, url)
result, err := exec.Run(ctx, req)
ips, err := resolver.LookupHost(ctx, hostname)

2. Close HTTP Response Bodies

resp, err := sdknet.Get(ctx, url)
if err != nil {
    return entities.ResultError(entities.NewErrorDetail("http", err.Error())), nil
}
defer resp.Body.Close() // ✅ Always defer close

body, _ := io.ReadAll(resp.Body)

3. Use Structured Logging

// ❌ Bad
slog.Info(fmt.Sprintf("User %s logged in", userID))

// ✅ Good
slog.Info("User logged in", "user_id", userID)

4. Handle Expected Errors Gracefully

result, err := exec.Run(ctx, req)
if err != nil {
    // Unexpected error (command not found, permission denied)
    return entities.ResultError(entities.NewErrorDetail("exec", err.Error())), nil
}

if result.ExitCode != 0 {
    // Expected non-zero exit (command ran but failed)
    return entities.ResultSuccess("Check failed", map[string]any{
        "check_passed": false,
        "exit_code":    result.ExitCode,
        "stderr":       result.Stderr,
    }), nil
}

5. Request Minimal Capabilities

// ❌ Too broad
{Kind: "network:outbound", Pattern: "*"}

// ✅ Specific
{Kind: "network:outbound", Pattern: "api.example.com:443"}

Testing Plugins

Unit Testing

func TestMyPlugin_Check(t *testing.T) {
    plugin := &MyPlugin{}
    config := map[string]any{
        "hostname": "example.com",
    }

    ctx := context.Background()
    result, err := plugin.Check(ctx, config)

    require.NoError(t, err)
    assert.Equal(t, entities.ResultStatusSuccess, result.Status)
}

Testing Typed Operations

For plugins using typed operations, use GenerateExampleTests to auto-generate tests from registered examples:

func TestExamples(t *testing.T) {
    // Create mock client matching your service's expected client type
    mockClient := &mockDNSResolver{
        records: map[string][]string{
            "example.com": {"93.184.216.34"},
        },
    }

    // Runs all registered examples as subtests
    plugin.GenerateExampleTests(t, core.Plugin, mockClient)
}

// Test typed handlers directly
func TestResolve_Handler(t *testing.T) {
    svc := &DNSService{}

    ctx := context.Background()
    ctx = plugin.WithClient(ctx, &mockDNSResolver{...})

    out, err := svc.ResolveHandler(ctx, &ResolveInput{
        Hostname:   "example.com",
        RecordType: "A",
    })

    require.NoError(t, err)
    assert.Equal(t, "example.com", out.Hostname)
    assert.Contains(t, out.Records, "93.184.216.34")
}

For advanced test configuration:

func TestExamples_WithConfig(t *testing.T) {
    config := plugin.ExampleTestConfig{
        SkipExamples: []string{"slow_test", "requires_network"},
        MockClientFactory: func(exampleName string) any {
            // Return different mocks based on example
            if exampleName == "error_case" {
                return &mockDNSResolver{shouldFail: true}
            }
            return &mockDNSResolver{}
        },
    }

    plugin.GenerateExampleTestsWithConfig(t, core.Plugin, nil, config)
}

Integration Testing

# Build WASM plugin
GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm

# Run with reglet CLI
reglet check --profile test-profile.yaml

Troubleshooting

"memory allocation limit exceeded"

Cause: Your plugin exceeded the 100 MB memory limit.

Solutions:

• Stream data instead of loading into memory
• Close HTTP response bodies promptly
• Avoid caching large datasets
• Process data in chunks

"HTTP response body exceeds maximum size"

Cause: Response body > 10 MB.

Solutions:

• Request smaller data chunks (use pagination)
• Stream responses if host supports it
• Compress responses at source

"context deadline exceeded"

Cause: Operation took longer than context timeout.

Solutions:

• Increase context timeout
• Optimize slow operations
• Use concurrent requests (via goroutines)

Config Helpers

The application/config package provides safe extraction functions:

import "github.com/reglet-dev/reglet-sdk/go/application/config"

// Required fields - returns error if missing
hostname, err := config.MustGetString(cfgMap, "hostname")
port, err := config.MustGetInt(cfgMap, "port")

// Optional fields with defaults
timeout := config.GetIntDefault(cfgMap, "timeout", 30)
protocol := config.GetStringDefault(cfgMap, "protocol", "https")

// Safe extraction
value, ok := config.GetString(cfgMap, "optional_field")

Examples

See the examples directory for complete working plugins:

• plugin - A complete example plugin implementing a TLS check
• host-runtime - An example host runtime demonstrating how to execute plugins using the SDK host package

Contributing

See CONTRIBUTING.md for development guidelines.

License

See LICENSE for details.