Kyle Isom
ebe2079a83
All import paths updated from git.wntrmute.dev/kyle/mcdsl to git.wntrmute.dev/mc/mcdsl to match the Gitea organization. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
# 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/mc/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
|
|
|
|
```go
|
|
import (
|
|
"git.wntrmute.dev/mc/mcdsl/auth"
|
|
"git.wntrmute.dev/mc/mcdsl/db"
|
|
"git.wntrmute.dev/mc/mcdsl/config"
|
|
"git.wntrmute.dev/mc/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
|
|
|
|
```bash
|
|
go build ./...
|
|
go test ./...
|
|
go vet ./...
|
|
golangci-lint run ./...
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [ARCHITECTURE.md](ARCHITECTURE.md) — full library specification
|
|
- [PROJECT_PLAN.md](PROJECT_PLAN.md) — implementation phases
|
|
- [PROGRESS.md](PROGRESS.md) — development status
|
|
- [../engineering-standards.md](../engineering-standards.md) — platform-wide standards
|