README
¶
Scion
Graft backend patterns into your project. Copy source, not dependencies.
Scion is a copy-paste code library for Go backend development. It ships production-oriented modules as source templates, so you can copy them into your project, adapt them, and own every line.
Quick Start
Install the CLI with Go 1.22 or newer:
go install github.com/DarkInno/scion/cmd/scion@latest
For reproducible installs, pin a release:
go install github.com/DarkInno/scion/cmd/scion@v0.1.3
Make sure your Go bin directory is on PATH, then verify the install:
scion version
scion list
Copy a standard-library-only module into your project:
scion add cache --dry-run
scion add cache
scion diff cache
When --to or --target is omitted, Scion uses the module's default target, such as internal/cache. You can still override it with --to <dir> or --target <dir>.
Scion copies source files and writes .scion-module.json metadata for later comparison. It never edits your project's go.mod automatically. Modules marked stdlibOnly=false, such as auth and metrics, require explicit standalone mode:
scion add auth --standalone
Binary Downloads
Prebuilt binaries are available on the GitHub Releases page for macOS, Linux, and Windows on amd64 and arm64.
Verify a downloaded asset with SHA256SUMS:
sha256sum -c SHA256SUMS
On Windows PowerShell:
Get-FileHash .\scion_v0.1.3_windows_amd64.zip -Algorithm SHA256
Why Copy-Paste?
Backend modules such as auth, CRUD, file upload, and rate limiting share most of their structure across projects, but the last mile is usually project-specific:
- You need to customize business logic inside the module.
- You want to own the code instead of being locked to upstream APIs.
- AI coding assistants work better with source they can read and edit directly.
- Scion avoids dependency sprawl by default; security-sensitive exceptions are declared explicitly.
Available Modules
| Module | Description | Security Features |
|---|---|---|
| auth | JWT email/password auth + bcrypt | Rate limiting, user enumeration prevention, JTI, aud/iss validation |
| crud | Generic CRUD with pagination | Sort/filter whitelist, SQL injection prevention, pagination ceiling |
| database | database/sql setup + transactions |
DSN-safe errors, whitelisted SQL fragments, parameterized values |
| middleware | Recovery, CORS, logging, timeout, etc. | CRLF injection prevention, trusted proxy, body size limit |
| rbac | Role-based access control | Wildcard permissions, cycle detection, hierarchy inheritance |
| ratelimit | Fixed window / sliding window / token bucket | Memory exhaustion protection, LRU eviction, key length limit |
| validation | Chainable request validation builder | Regex DoS prevention, null byte/CRLF rejection, panic recovery |
| file-upload | Secure file upload handler | Magic bytes validation, path traversal prevention, size limit, rate limiting |
| health | Liveness/readiness probes | SSRF protection, CRLF injection prevention |
| cache | Generic TTL + LRU cache | Background cleanup, goroutine leak prevention, max entries limit |
| pagination | Offset/limit + cursor pagination | Cursor base64 validation, negative offset clamp, max limit enforcement |
| SMTP email with templates | Header injection prevention, XSS escaping, attachment sanitization, async queue | |
| migrations | SQL migration runner | Safe filenames, table whitelist, checksums, transactions |
| metrics | Prometheus HTTP metrics | Route cardinality limits, label sanitization, isolated registry |
| problem | RFC 9457 problem responses | CRLF/null rejection, detail truncation, panic recovery |
CLI Commands
scion list [--json]
scion info <module> [--json]
scion add <module> [--to <dir>] [--dry-run] [--force] [--standalone]
scion diff <module> [--target <dir>] [--json]
scion doctor [--strict] [--json]
scion version [--json]
Use scion help <command> for command-specific examples.
Project Structure
scion/
|-- cmd/scion/ # CLI entrypoint
|-- internal/ # CLI implementation, bundle reader, doctor checks
|-- internal/bundle/ # Embedded registry bundle generated from registry/
|-- registry/
| |-- index.json # Machine-readable module index
| |-- auth/ # Authentication module
| |-- cache/ # TTL + LRU cache
| |-- crud/ # CRUD operations module
| |-- database/ # database/sql helpers
| |-- file-upload/ # File upload handler
| |-- health/ # Health check probes
| |-- mail/ # SMTP email sender
| |-- metrics/ # Prometheus HTTP metrics
| |-- migrations/ # SQL migration runner
| |-- middleware/ # HTTP middleware collection
| |-- pagination/ # Pagination utilities
| |-- problem/ # Problem Details API errors
| |-- ratelimit/ # Rate limiting algorithms
| |-- rbac/ # Role-based access control
| `-- validation/ # Request validation builder
|-- docs/ # VitePress documentation
|-- AGENTS.md # AI coding agent instructions
|-- CONTRIBUTING.md # Contribution guide
`-- LICENSE # MIT
Development
git clone https://github.com/DarkInno/scion.git
cd scion
# Regenerate the embedded CLI bundle after registry changes
go run ./internal/cmd/build-bundle
# Test and vet the root CLI
go test ./cmd/... ./internal/...
go vet ./cmd/... ./internal/...
# Run strict registry checks
go run ./cmd/scion doctor --strict
Run tests for all registry modules in PowerShell:
$modules = @('middleware','auth','crud','database','rbac','ratelimit','validation','file-upload','health','cache','pagination','mail','migrations','metrics','problem')
foreach ($m in $modules) { Push-Location "registry/$m/src/go"; go test ./...; Pop-Location }
Releasing
Releases are created from semantic version tags:
git tag -a v0.1.3 -m "v0.1.3"
git push origin v0.1.3
The release workflow verifies the CLI, rebuilds the embedded bundle check, cross-compiles binaries, generates SHA256SUMS, and publishes GitHub Release assets.
Directories