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