Amber V2: zero-dependency library, Schema API, typed config, built-in jobs/mailer, modernized WebSockets [BETA]

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - v2-dev
+  pull_request:
+    branches:
+      - master
+      - v2-dev
+
+jobs:
+  test:
+    name: Crystal ${{ matrix.crystal }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        crystal: [latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Crystal
+        uses: oprypin/install-crystal@v1
+        with:
+          crystal: ${{ matrix.crystal }}
+
+      - name: Install dependencies
+        run: shards install
+
+      - name: Run specs
+        # Defined order for now: the suite has pre-existing order-dependent
+        # specs (respond_with + others fail under --order random regardless of
+        # recent changes). Tracked as a cleanup task before switching to random.
+        run: crystal spec
+
+      - name: Check formatting
+        run: crystal tool format --check

.gitignore

@@ -1,5 +1,4 @@
 /doc/
-/docs/
 /bin/
 /.shards/
 /.vscode/
@@ -10,7 +9,7 @@ lib/
 /tmp
 shard.lock
 .crystal-version
-package-lock.json
-node_modules
 /myapp
-cli.dwarf
+*.dwarf
+*.bak
+*.png

Backers.md

@@ -1,3 +1,3 @@
-As of 2019-05-30, Amber is graciously supported by:
+As of 2025-07-25, Amber is graciously supported by:
 
-Universal Layer - https://ulayer.net/
+AgentC Consulting - https://agentc.consulting

CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+## 2.0.0-dev (unreleased)
+
+This release represents a major architectural revision of the Amber framework.
+The primary goals were to remove all runtime dependencies, modernize the
+Crystal language patterns in use, and add first-class support for background
+jobs, email, and typed configuration. The CLI has been extracted to a separate
+repository.
+
+### Breaking Changes
+
+#### CLI removed from framework
+
+The `amber` CLI tool — generators, scaffolding, database commands, `amber
+watch`, `amber routes`, `amber encrypt`, `amber exec` — has been removed from
+this repository. Amber V2 is a library shard, not a CLI tool.
+
+A replacement CLI is maintained as a separate project:
+https://github.com/amberframework/amber_cli
+
+#### Zero runtime dependencies
+
+All runtime shards have been removed from `shard.yml`. The following were
+either dropped or internalized:
+
+| Dependency | Disposition |
+|---|---|
+| `redis` / `crystal-redis` | Replaced by adapter pattern; memory adapter is default |
+| `amber_router` | Internalized into `src/amber/router/engine/` |
+| `backtracer` | Internalized into `src/amber/` |
+| `exception_page` | Internalized into `src/amber/` |
+| `kilt` | Removed; ECR only |
+| `slang` | Removed; ECR only |
+| `pg` / `mysql` / `sqlite3` | Removed; add the driver you need at app level |
+| `compiled_license` | Removed |
+| `micrate` | Removed; handle migrations at app level |
+
+The only remaining dependency is `ameba` (development only) for linting.
+
+#### Template engine: ECR only
+
+Kilt and Slang have been removed. Templates must use Crystal's built-in ECR
+(Embedded Crystal). Rename `.slang` files to `.ecr` and convert syntax
+accordingly. See [docs/migration-guide.md](docs/migration-guide.md) for a
+conversion table.
+
+#### YAML.mapping replaced with YAML::Serializable
+
+The deprecated `YAML.mapping` macro no longer works in Crystal 1.x. All
+framework internals have been updated to `include YAML::Serializable`. Any
+application code using `YAML.mapping` must be updated; the change is
+mechanical (see migration guide).
+
+#### Configuration restructured
+
+The flat YAML configuration format has been replaced with typed, sectioned
+configuration structs. Sections: `server`, `database`, `session`, `logging`,
+`jobs`, `mailer`. Every property can be overridden with an environment variable
+using the `AMBER_{SECTION}_{KEY}` naming convention (e.g.,
+`AMBER_SERVER_PORT=8080`, `AMBER_DATABASE_URL=postgres://...`).
+
+The `Amber::Server.configure` block no longer accepts a block parameter;
+properties are set directly inside the block.
+
+#### Session defaults changed
+
+Default session store changed from `redis` to `signed_cookie`. Default adapter
+is `memory` (no external service required). The `expires` field is an integer
+(seconds).
+
+### New Features
+
+#### Schema API
+
+A type-safe request validation and coercion layer. Define a schema class with
+typed fields and validators (required, length, format, range, pattern, enum).
+Parsers handle JSON, multipart, query string, and XML bodies. Existing
+`params["key"]` usage continues to work unchanged via `SchemaParamsWrapper`;
+the Schema API is opt-in per action.
+
+See [docs/guides/schema-api.md](docs/guides/schema-api.md).
+
+#### Typed configuration with environment variable overrides
+
+`Amber::Configuration::AppConfig` holds all framework settings as typed Crystal
+structs. Any field can be overridden at runtime via environment variables
+following the `AMBER_{SECTION}_{KEY}` pattern without changing YAML files.
+Custom configuration sections can be registered in the same registry.
+
+See [docs/guides/configuration.md](docs/guides/configuration.md).
+
+#### Built-in background jobs
+
+A work-stealing job queue that runs inside idle web workers — no separate
+process required. Includes retry logic and a pluggable adapter interface (memory
+adapter ships by default). Redis and other backends can be added via custom
+adapters.
+
+See [docs/guides/background-jobs.md](docs/guides/background-jobs.md).
+
+#### Built-in mailer
+
+Fluent API for composing and sending email. Ships with an SMTP adapter and a
+memory adapter for testing. The memory adapter records sent mail so tests can
+assert on it without a real mail server.
+
+See [docs/guides/mailer.md](docs/guides/mailer.md).
+
+#### WebSocket modernization
+
+- Message decoders: plug in a decoder to parse incoming frames into typed
+  messages before they reach your channel handler
+- Presence tracking: built-in presence API that tracks which users are
+  connected and broadcasts join/leave events
+- Connection recovery: automatic reconnect with exponential backoff and
+  last-message-id replay
+- Improved error handling and channel lifecycle callbacks
+
+See [docs/guides/websockets.md](docs/guides/websockets.md).
+
+#### Named routes, constraints, and API versioning
+
+- `route_url(:route_name, param: value)` — generate URLs by name rather than
+  hardcoded strings
+- Route constraints: host, subdomain, format, and custom lambda constraints
+- API versioning middleware (`ApiVersion` pipe) with header- and
+  URL-segment-based version detection
+- Route introspection: list all registered routes with names, methods, and
+  paths at runtime
+
+See [docs/guides/routing.md](docs/guides/routing.md).
+
+#### Built-in markdown renderer
+
+A GFM-compatible Markdown renderer with autolinks, footnotes, table-of-contents
+generation, and syntax highlighting hooks. No external dependency.
+
+See [docs/guides/markdown.md](docs/guides/markdown.md).
+
+#### Action helpers
+
+Helper methods for views: form builders, URL helpers, asset helpers, text
+formatting, and number formatting.
+
+See [docs/guides/action-helpers.md](docs/guides/action-helpers.md).
+
+#### Built-in test framework
+
+`Amber::Testing::ContextBuilder` simulates HTTP requests against your
+controllers without starting a real server. Includes WebSocket test helpers and
+assertion methods for response status, headers, body content, and redirects.
+
+See [docs/guides/testing.md](docs/guides/testing.md).
+
+#### Session security improvements
+
+`MessageEncryptor` and `MessageVerifier` updated to SHA-256. SameSite cookie
+attribute support. Key rotation support. Session regeneration on privilege
+escalation.
+
+### Adapter Pattern
+
+Sessions, PubSub, jobs, and mailer now all use a pluggable adapter interface.
+The `AdapterFactory` allows registering custom backends at startup. This is the
+supported path for adding Redis sessions, Redis pub/sub, or any other backend
+without coupling the framework to a specific shard.
+
+### Documentation
+
+A full documentation suite has been added under `docs/`:
+
+- [Migration guide](docs/migration-guide.md) — complete V1 to V2 upgrade instructions
+- [Schema API guide](docs/guides/schema-api.md)
+- [Configuration guide](docs/guides/configuration.md)
+- [Routing guide](docs/guides/routing.md) (named routes, constraints, API versioning)
+- [WebSocket guide](docs/guides/websockets.md)
+- [Background jobs guide](docs/guides/background-jobs.md)
+- [Mailer guide](docs/guides/mailer.md)
+- [Testing guide](docs/guides/testing.md)
+- [Markdown guide](docs/guides/markdown.md)
+- [Action helpers guide](docs/guides/action-helpers.md)
+- [LSP setup guide](docs/guides/lsp-setup.md) (Claude Code integration)
+
+---
+
+For changes prior to V2, see the git log at
+https://github.com/amberframework/amber/commits/master

CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+## Project Overview
+
+Amber V2 is a web application framework written in Crystal. It provides an efficient, cohesive framework that embraces Crystal's language philosophies with near-zero runtime dependencies.
+
+**Version**: 2.0.0-dev
+**Crystal**: >= 1.0.0, < 2.0
+**License**: MIT
+**Dependencies**: ameba (dev only) — framework is entirely self-contained at runtime
+
+## Development Commands
+
+```bash
+# Install dependencies (ameba only)
+shards install
+
+# Run all tests and checks (recommended)
+./bin/amber_spec
+
+# Individual commands
+crystal spec                   # Run test suite
+crystal spec spec/amber/controller/base_spec.cr  # Single file
+crystal tool format --check    # Check formatting
+crystal tool format            # Auto-format
+./bin/ameba                    # Run linter
+crystal docs                   # Generate API docs → docs/
+```
+
+## Architecture Overview
+
+### Core Subsystems
+
+1. **Controllers** (`src/amber/controller/`): Base controller with before/after filters, rendering, redirects, CSRF helpers, route helpers, responders, i18n
+
+2. **Router** (`src/amber/router/`): HTTP routing with params, cookies, sessions, flash messages, file uploads. V2 adds named routes, constraints (host, subdomain, format, custom), and API versioning
+
+3. **Router Engine** (`src/amber/router/engine/`): Internalized radix-tree router (formerly amber_router shard). Segment-based matching with fixed, variable, and glob segments
+
+4. **Middleware Pipes** (`src/amber/pipes/`): Pipeline-based HTTP request processing — CSRF, Session, Flash, Logger, CORS, Static, Error, ClientIp, ApiVersion, PoweredByAmber
+
+5. **WebSockets** (`src/amber/websockets/`): Channel-based real-time communication with presence tracking, message decoders, connection recovery, and adapter-backed PubSub
+
+6. **Configuration** (`src/amber/configuration/`): Typed configuration structs with YAML loading, environment variable overrides (`AMBER_` prefix), validation, and custom registry
+
+7. **Schema API** (`src/amber/schema/`): Request validation and type coercion. Define schemas with field types, validators (required, length, format, range, pattern, enum), and parsers (JSON, multipart, query, XML)
+
+8. **Jobs** (`src/amber/jobs/`): Background job processing with work-stealing pattern — idle web instances pick up queued jobs. Retry logic, queue adapters
+
+9. **Mailer** (`src/amber/mailer/`): Email composition with fluent API, SMTP adapter, memory adapter for testing
+
+10. **Testing** (`src/amber/testing/`): ContextBuilder for request simulation, assertions, WebSocket test helpers
+
+11. **Adapters** (`src/amber/adapters/`): Pluggable backends for sessions (Memory, with adapter interface for Redis/others) and PubSub (Memory, with adapter interface). Factory pattern for runtime selection
+
+12. **Markdown** (`src/amber/markdown/`): GFM-compatible renderer with autolinks, footnotes, table of contents, syntax highlighting
+
+13. **Session Security** (`src/amber/support/`): MessageEncryptor and MessageVerifier with SHA256, SameSite cookies, key rotation, session regeneration
+
+14. **DSL** (`src/amber/dsl/`): Macros for server configuration, router definition, pipeline composition, and callback registration
+
+### Template Engine
+
+ECR (Embedded Crystal) only — part of Crystal stdlib. Kilt/Slang/Liquid have been removed.
+
+### Key Design Patterns
+
+- **Adapter Pattern**: Sessions, PubSub, jobs, and mailer use adapters for different backends
+- **Pipeline Pattern**: HTTP requests flow through configurable middleware pipes
+- **DSL Approach**: Router and server configuration use Crystal macros for clean syntax
+- **Work-Stealing**: Background jobs distributed across idle web instances
+- **Convention over Configuration**: Sensible defaults with typed overrides
+
+### Using Amber Without HTTP Server (Native Apps)
+
+Amber can be used as a pattern library for native desktop/mobile apps without starting the HTTP server. This is useful when you want Amber's configuration, controllers-as-event-handlers, and process managers but use a native event loop instead.
+
+**Settings API:**
+```crystal
+require "amber"
+
+# Correct: access settings directly
+Amber.settings.name = "My Native App"
+puts Amber.env  # => "development"
+
+# WRONG: Amber::Server.configure creates an HTTP server instance
+# Amber::Server.configure { |s| s.name = "..." }  # Don't do this
+
+# WRONG: Amber::Server.settings doesn't exist
+# Amber::Server.settings.name  # NoMethodError
+```
+
+**Key point:** `Amber.settings` returns `Amber::Environment::Settings` and can be used standalone. `Amber::Server.configure` yields settings but also instantiates `Amber::Server.instance` which initializes HTTP-related adapters.
+
+### External Dependencies
+
+- **Grant ORM**: Separate shard — ActiveRecord-style ORM for V2 (publishing to the amberframework org soon)
+- **CLI**: Separate project (`amber_cli`) — not part of this repo
+- **Asset Pipeline**: Separate project (`amberframework/asset_pipeline`) — not part of this repo
+
+## Key File Paths
+
+| Area | Path |
+|------|------|
+| Entry point | `src/amber.cr` |
+| Configuration | `src/amber/configuration/` |
+| Controllers | `src/amber/controller/` |
+| Router + Engine | `src/amber/router/`, `src/amber/router/engine/` |
+| Named Routes | `src/amber/router/named_routes.cr` |
+| Constraints | `src/amber/router/constraints/` |
+| Middleware | `src/amber/pipes/` |
+| WebSockets | `src/amber/websockets/` |
+| Schema API | `src/amber/schema/` |
+| Jobs | `src/amber/jobs/` |
+| Mailer | `src/amber/mailer/` |
+| Testing | `src/amber/testing/` |
+| Adapters | `src/amber/adapters/` |
+| Markdown | `src/amber/markdown/` |
+| Session Security | `src/amber/support/message_encryptor.cr`, `message_verifier.cr` |
+| DSL | `src/amber/dsl/` |