MCDSL — Metacircular Dynamics Standard Library

MCDSL is a shared Go library for Metacircular Dynamics services. It extracts the common patterns that every service implements independently — MCIAS authentication, SQLite database setup, TLS server bootstrapping, CSRF protection, configuration loading, and service data snapshots — into a single, tested, reusable module.

Why

Every Metacircular service follows the same patterns (see engineering-standards.md). Today, each service copy-pastes these patterns into its own internal/ packages. This means:

• Bug fixes must be applied N times (once per service).
• Subtle divergences accumulate (e.g., CSRF tokens use base64 in one service, hex in another; auth cache keys are [32]byte in some, hex strings in others).
• New services require copying and adapting boilerplate from an existing service.

MCDSL extracts the 95%+ identical code into a shared library. Services import it and provide only their service-specific logic.

Module Path

git.wntrmute.dev/kyle/mcdsl

Packages

Package	Purpose
auth	MCIAS token validation with 30-second SHA-256 cache
db	SQLite connection setup (WAL, FK, busy timeout), migration runner, VACUUM INTO snapshots
config	TOML config loading with environment variable overrides, standard section types
httpserver	TLS 1.3 HTTP server setup with chi, graceful shutdown, logging middleware
grpcserver	gRPC server setup with TLS, interceptor chain helpers, method map auth
csrf	HMAC-SHA256 double-submit cookie CSRF protection
web	Session cookie management, template rendering helpers, auth middleware
archive	tar.zst service directory snapshot and restore with SQLite-aware handling
health	Standard health check implementation (gRPC Health/v1 + REST)

Quick Start

import (
    "git.wntrmute.dev/kyle/mcdsl/auth"
    "git.wntrmute.dev/kyle/mcdsl/db"
    "git.wntrmute.dev/kyle/mcdsl/config"
    "git.wntrmute.dev/kyle/mcdsl/httpserver"
)

// Load config with standard sections + service-specific fields.
type MyConfig struct {
    config.Base
    MyService MyServiceConfig `toml:"my_service"`
}

cfg, err := config.Load[MyConfig]("my-service.toml", "MYSERVICE")

// Timeout fields use config.Duration (go-toml v2 doesn't decode
// strings to time.Duration natively). Access via .Duration:
readTimeout := cfg.Server.ReadTimeout.Duration  // time.Duration

// Open database with standard pragmas and run migrations.
database, err := db.Open(cfg.Database.Path)
migrations := []db.Migration{
    {Version: 1, Name: "initial schema", SQL: `CREATE TABLE ...`},
}
db.Migrate(database, migrations)

// Set up MCIAS authentication with token caching.
mcauth, err := auth.New(cfg.MCIAS)

// Start TLS server with standard middleware.
srv := httpserver.New(cfg.Server, logger)
srv.Route(func(r chi.Router) {
    r.Use(srv.LoggingMiddleware)
    // register routes...
})
srv.ListenAndServeTLS()

Build and Test

go build ./...
go test ./...
go vet ./...
golangci-lint run ./...

Documentation

• ARCHITECTURE.md — full library specification
• PROJECT_PLAN.md — implementation phases
• PROGRESS.md — development status
• ../engineering-standards.md — platform-wide standards