Amber 2.0.0-beta.5

Amber 2.0.0-beta.5 turns the V2 schema API into a contract the framework actually enforces. A controller declaration now owns request parsing, validation, typed access, response validation, content negotiation, and OpenAPI 3.1 output. The release also brings the optimized router and request path onto the V2 release line.

Upgrade compatibility comes first

The existing params.validation API still compiles and runs. It is deprecated so new work can use executable controller schemas, but upgrading to beta.5 does not require rewriting every controller. Applications can update Amber, run their existing tests, and then migrate one action at a time.

Amber does not plan to remove the deprecated validator before a later V2 minor such as 2.5. The exact removal release will be announced separately.

Executable request and response contracts

• schema :action, SchemaClass enforces the declared request before the action runs.
• validated_as(SchemaClass) exposes request-local typed values without constructing and validating a second schema object.
• Request fields can come from bodies, paths, query strings, headers, and cookies.
• response_schema verifies the declared status, content type, and response shape before delivery.
• OpenAPI 3.1 operations are generated from the same contracts the application executes.
• Server-rendered controllers can override the schema-failure hook to return an ECR form with field errors and the correct 400, 415, or 422 status.

JSON, CBOR, and authenticated COSE

Amber now supports JSON, XML, URL-encoded forms, multipart forms, and bounded CBOR request parsing. COSE Encrypt0 adds authenticated ChaCha20-Poly1305 encryption in both directions: Amber decrypts and authenticates the inbound request, applies its schema, and can authenticate and encrypt the response with a fresh nonce.

The request boundary fails explicitly for malformed documents, unsupported media, invalid values, unacceptable response formats, invalid declared responses, and temporarily unavailable encryption configuration.

Measured performance

The release candidate was tested on a DigitalOcean Basic one-shared-vCPU, 512-MB-class target with a separate load generator, 16 keep-alive connections, and seven rotating 15-second repetitions per scenario:

All 7,974,608 retained requests returned HTTP 200. This is a synthetic in-memory acknowledgement workload without a database, TLS termination, external services, or HTML rendering. It measures framework, codec, and schema cost under constrained hardware; it is not a capacity promise for an arbitrary production application.

See benchmarks/DIGITALOCEAN_SCHEMA_CONTRACT_ROUND27.md for the complete method, ranges, before-and-after comparison, and evidence paths.

Start a fresh web application

Amber CLI 2.0.6 is the coordinated generator release for this beta:

brew install amberframework/amber_cli/amber_cli
amber new pet_tracker --type web
cd pet_tracker
shards install
amber assets check
amber generate scaffold Pet name:string:required species:string:required adopted:bool
amber database migrate
crystal spec
amber watch

The generated application uses ECR, Grant, SQLite, Micrate, local front-end assets, executable HTML form schemas, and Amber 2.0.0-beta.5.

See the beta installation guide, migration guide, and schema guide.

Amber 2.0.0-beta.4 connects the V2 web runtime to the deterministic asset compiler and closes the fresh-application path across macOS, Linux, Linux ARM64, and Windows CI.

The beta label applies to the Amber 2.0 release train. The supported surface is the ECR web application created by Amber CLI 2.0.5; native applications and authentication generators remain explicitly marked preview features.

What ships

• Manifest-backed asset_path, stylesheet, JavaScript/import-map, image, and favicon helpers with Subresource Integrity metadata.
• Production manifest caching and development reload behavior.
• Immutable cache headers plus correct media type and content-length metadata for fingerprinted assets.
• Precompressed gzip negotiation, byte ranges, conditional requests, HEAD, and safe non-fingerprinted fallback behavior.
• AMBER_DATABASE_URL configuration with DATABASE_URL fallback for generated Grant applications.
• Windows-safe server startup: Amber no longer invokes Crystal's unimplemented Windows signal-trap API.
• Updated installation, migration, asset-helper, configuration, and release-contract documentation with exact file locations.

Supported fresh web-app contract

The release-gated path covers generation, dependency installation, asset compilation and verification, Grant/SQLite/Micrate migrations, resource scaffolds, specs, production compilation, server startup, the generated homepage, and live database CRUD.

• macOS Apple Silicon: supported and release-gated.
• Linux x86_64: supported and release-gated.
• Linux ARM64: supported and release-gated.
• Windows x86_64: the generated application path is release-gated in CI; build the CLI from source because a standalone Windows archive is not published yet.

Validation

• 2,350 framework examples passed with no failures.
• GitHub Actions passed on Linux and macOS; CircleCI passed.
• The Windows generated-app gate compiles and runs this exact framework revision through Amber CLI CI.

Use Amber CLI 2.0.5 to create a new web application. See docs/beta-installation.md and docs/migration-guide.md in the repository for the reproducible install and upgrade procedures.

Full change: #1407

Amber 2.0.0-beta.3

Amber 2.0.0-beta.3 is the framework release for the database-backed web application that Amber CLI 2.0.4 generates by default. The supported path now includes Grant models, SQLite, Micrate migrations, and complete HTML resource scaffolds instead of stopping at a database-free homepage.

What changed

• Schema controllers parse browser form bodies, including bodies already read by routing or CSRF protection.
• Background-job workers can steal queued work without corrupting request activity accounting.
• ECR view paths are normalized on Windows.
• The HTML/JSON respond_with behavior is documented with executable examples.

Install and exercise persistence

Install Amber CLI 2.0.4, then generate and migrate a real resource:

brew install amberframework/amber_cli/amber_cli
amber new pet_tracker --type web
cd pet_tracker
shards install
amber generate scaffold Pet name:string:required species:string:required adopted:bool
amber database migrate
crystal spec
amber watch

Open http://localhost:3000/pets. The generated model lives at src/models/pet.cr, its SQL migration is under db/migrations/, and its ECR form partial is src/views/pet/_form.ecr.

Amber CLI 2.0.4 ships release archives for Apple Silicon macOS, x86_64 Linux, and ARM64 Linux. Windows x86_64 generated web applications are compile-gated in CI; build the CLI from source on Windows for this beta.

See the beta installation guide and V1 to V2 migration guide.

Please report framework issues at https://github.com/amberframework/amber/issues and CLI/template/install issues at https://github.com/amberframework/amber_cli/issues.

Amber 1.5.0 — Crystal 1.21 support

Crystal 1.21 enables multithreading by default, which made Process.fork a compile-time error — and broke compilation of every Amber app on Crystal 1.21.0+ (Error: Process fork is unsupported with multithreaded mode). This release restores compatibility and ships the security and performance work that had been waiting in review.

Compatibility

• Amber::Cluster.fork no longer uses Process.fork (#1399) — cluster workers are spawned with Process.new (same mechanism as v2). process_count / master-worker semantics unchanged. Verified: framework specs, amber new → build → serve, and cluster mode with 2 workers, on Crystal 1.20.3 and 1.21.0.
• ameba pinned to 1.7.0-dev in framework dev-dependencies and the generated app template (#1399, supersedes #1394 — thanks @botantony). ameba ≤ 1.6.4 fails to build on Crystal 1.21, which broke shards install for new apps.
• New COMPATIBILITY.md documents which Crystal versions build which Amber releases.
• Declared Crystal requirement is now >= 1.20.0, < 2.0 (previously >= 1.0.0, which overstated reality).

Security (thanks @renich)

• XSS: exception messages are HTML-escaped in the default error response (#1385).
• Command injection: amber encrypt no longer passes the editor command through a shell (#1388).
• DoS hardening: MessageVerifier / MessageEncryptor reject malformed payloads with typed exceptions instead of raising IndexError (#1386).
• SecureHeaders pipe (#1390): new apps get X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, and Referrer-Policy out of the box, plugged above the Error pipe so 404/403 responses keep their headers; HSTS is opt-in (SecureHeaders.new(hsts: true)).

Performance

• Router content-extension matching uses string ops + set lookup instead of regex alternation (#1387, #1391, thanks @renich).

CI / contributor experience

• CircleCI (broken at the project level) replaced with GitHub Actions: spec matrix on Crystal 1.20.3 + latest, Linux + macOS.
• Contributor review rubric, PR template, and local dev hooks (#1393).

Upgrade notes

• If your app pins amber to 1.4.1 exactly (the default for apps generated by older CLIs), change it to ~> 1.5.0 in shard.yml to build on Crystal 1.21.
• Existing apps do not get SecureHeaders automatically — it's wired in the new-app template. Add plug Amber::Pipe::SecureHeaders.new above plug Amber::Pipe::Error.new in your config/routes.cr to adopt it.

Amber 2.0.0-beta.2

Amber 2.0.0-beta.2 supersedes beta.1 for new Amber CLI web applications. It keeps the same public beta surface and fixes application startup on Crystal 1.21's default multithreaded runtime.

Compatibility fix

• Replaced the server cluster launcher's Process.fork reference with portable process spawning.
• Release-gated on Apple Silicon macOS and x86_64 Linux with Crystal 1.21.
• Fresh ECR web apps are tested through dependency installation, specs, core generators, build, server launch, homepage delivery, and static CSS.

Install and create a web app

Install Amber CLI 2.0.2 or newer:

brew install amberframework/amber_cli/amber_cli
amber new my_app --type web
cd my_app
shards install
crystal spec
amber watch

The generated application pins amberframework/amber at 2.0.0-beta.2 and uses ECR. Database drivers, persistence, auth, Grant, Gemma, Asset Pipeline, and native application generation remain opt-in preview surfaces rather than part of the core beta release gate.

See the beta installation guide and V1 to V2 migration guide.

Please report framework issues at https://github.com/amberframework/amber/issues and CLI/template/install issues at https://github.com/amberframework/amber_cli/issues.

Amber 2.0.0-beta.1

Amber V2's first public beta establishes a tested, documented path for creating an ECR web application with the standalone Amber CLI.

This is a prerelease. Expect breaking changes before Amber 2.0.0 and do not use it for production workloads that cannot tolerate them.

Install and create a web app

Install Amber CLI 2.0.2 or newer:

brew install amberframework/amber_cli/amber_cli
amber new my_app --type web
cd my_app
crystal spec
amber watch

See the beta installation guide for direct archives, checksums, update/uninstall steps, and troubleshooting.

Release-gated surface

• Apple Silicon macOS and x86_64 Linux
• Homebrew and matching direct CLI archives
• ECR web application generation
• dependency installation, specs, application build, server start, homepage, and static CSS
• framework core, routing, typed configuration, Schema API, jobs, mailer, WebSockets, adapters, and testing helpers

Major V2 changes

• CLI and LSP extracted to amberframework/amber_cli
• ECR is the only supported view engine; Kilt and Slang were removed
• runtime shard dependencies removed from framework core
• database drivers and ORM are explicit application choices
• typed, sectioned YAML with environment-variable overrides
• built-in jobs, mailer, Schema API, and adapter-backed infrastructure

Read the V1 to V2 migration guide before upgrading an existing application.

Preview surfaces

Persistence/auth/API-resource generators, Grant integration, Gemma attachments, the separate Asset Pipeline, and native app generation are not part of the core beta release gate. Intel macOS, Linux ARM64, and Windows do not have release-gated CLI archives in this beta.

Please report framework issues at https://github.com/amberframework/amber/issues and CLI/template/install issues at https://github.com/amberframework/amber_cli/issues.

What's Changed

• Fixes tests that check for "charset=utf-8" in the Content-Type header when application/json is the content type.
• Alters the Static pipeline slightly. When a directory is trying to be accessed but the trailing slash is not provided, the request will first redirect before returning a 404 if directory_listing is false (the default behavior). Previously, the redirect would have been skipped and just returned.

• Resolved failing tests from merged PRs in v1.4.0 by @crimson-knight in https://github.com/amberframework/amber/pull/1335

Full Changelog: https://github.com/amberframework/amber/compare/v1.4.0...v1.4.1

What's Changed

• feat!: remove webpack from dependencies by @drujensen in https://github.com/amberframework/amber/pull/1304
• update exception_page to 0.3.0 by @timstapl in https://github.com/amberframework/amber/pull/1315
• #1311 Replace json_mapping with JSON::Serializable by @schodevio in https://github.com/amberframework/amber/pull/1314
• Shard updates, mysql uuid type, and api route bug fix by @kalinon in https://github.com/amberframework/amber/pull/1319
• Explicitly declare the UTF-8 charset for json responses by @damianham in https://github.com/amberframework/amber/pull/1231
• Update README.md by @crimson-knight in https://github.com/amberframework/amber/pull/1323
• docs: update homebrew installation note by @chenrui333 in https://github.com/amberframework/amber/pull/1330
• Updated Ameba to use v1.5 by @crimson-knight in https://github.com/amberframework/amber/pull/1332
• Minor version bump by @crimson-knight in https://github.com/amberframework/amber/pull/1333

New Contributors

• @timstapl made their first contribution in https://github.com/amberframework/amber/pull/1315
• @schodevio made their first contribution in https://github.com/amberframework/amber/pull/1314
• @kalinon made their first contribution in https://github.com/amberframework/amber/pull/1319
• @chenrui333 made their first contribution in https://github.com/amberframework/amber/pull/1330

Full Changelog: https://github.com/amberframework/amber/compare/v1.3.2...v1.4.0

Amber CLI 2.0.6

Amber CLI 2.0.6 is the coordinated generator release for Amber 2.0.0-beta.5. Fresh web applications now use the framework's automatically enforced schema contracts instead of constructing and validating a second schema object inside each controller action.

Generate a complete web application

amber new pet_tracker --type web
cd pet_tracker
shards install
amber assets check
amber generate scaffold Pet name:string:required species:string:required adopted:bool
amber database migrate
crystal spec
amber watch

The generated project pins canonical Amber 2.0.0-beta.5, uses ECR, Grant, SQLite, Micrate, local front-end assets, and a manifest-backed asset pipeline.

What changed

• Resource scaffolds bind PetSchema automatically to create and update and read typed request-local values with validated_as(PetSchema).
• HTML form schemas declare URL-encoded input and return the generated ECR form with visible field errors and HTTP 422 when a well-formed request is invalid.
• Malformed or unsupported form bodies preserve the framework's explicit 400 or 415 status instead of being flattened into a generic validation error.
• Preview API generators bind the same executable schema contract for JSON writes while retaining structured JSON failures.
• amber generate schema teaches the executable controller declaration as the primary application path; direct construction remains available for isolated schema unit tests.
• The Unix and Windows generated-app smoke harnesses can test an exact framework repository and commit during coordinated development, while normal and release CI now exercise the published beta emitted by the template.

Upgrade compatibility

Amber's deprecated params.validation API remains functional. Existing Amber applications can update the framework first, verify their current behavior, and migrate validation one controller action at a time. CLI 2.0.6 changes new generators; it does not force an existing application to regenerate its controllers.

Release proof

• 412 Amber CLI examples pass.
• Apple Silicon macOS and x86_64 Linux release-style binaries generate, build, migrate, run, and exercise the complete web application.
• Linux ARM64 and Windows x86_64 compile and run the generated web application in GitHub Actions.
• The Pet Tracker smoke proves invalid HTML form input returns one HTML document with status 422 and a visible field error before proving persisted create and PATCH update behavior.
• Fingerprinted CSS, JavaScript, SVG, and favicon responses retain integrity, MIME, immutable caching, URL rewriting, and gzip checks.

Windows remains a source-build compatibility path; this release publishes CLI archives for Apple Silicon macOS, x86_64 Linux, and ARM64 Linux.

Amber CLI 2.0.5

Amber CLI 2.0.5 makes production-safe static assets part of the same supported Amber V2 web-app path as Grant, Micrate, and SQLite. A fresh application starts with editable CSS, JavaScript, SVG, and font locations; a deterministic asset manifest; manifest-aware ECR helpers; and browser-correct production headers.

Start a complete web app

amber new pet_tracker --type web
cd pet_tracker
shards install
amber assets check
amber generate scaffold Pet name:string:required species:string:required adopted:bool
amber database migrate
crystal spec
amber watch

Open http://127.0.0.1:3000/ and http://127.0.0.1:3000/pets. The homepage uses the same Amber design language as the framework site and references fingerprinted files from public/assets/manifest.json.

What changed

• Added amber assets build for deterministic fingerprinting and amber assets check for strict release verification.
• Moved authored browser files to app/assets/; generated files under public/assets/ are ignored and may be rebuilt at any time.
• Rewrites local CSS URLs and JavaScript module references to their fingerprinted image, font, stylesheet, and module targets.
• Generates manifest-aware stylesheet, import-map, preload, image, and favicon tags, including Subresource Integrity metadata where browsers support it.
• Rebuilds assets before application compilation in amber watch, including file additions, changes, and deletions.
• Boots generated applications in Unix and Windows CI and requests the real HTML, CSS, JavaScript, SVG, and compressed-asset paths instead of treating a successful compile as sufficient evidence.
• Publishes CLI archives for Apple Silicon macOS, x86_64 Linux, and ARM64 Linux; Windows x86_64 remains a source-build path with a release-gated app smoke.
• Replaces the native preview generator's old personal and feature branches with the canonical Amber beta, released Asset Pipeline, and exact reviewed dependency revisions. Its documented make setup now fails visibly when dependencies cannot install instead of hiding the error.

Grant, SQLite, Micrate migrations, and generated HTML resource CRUD remain the default persistence contract from CLI 2.0.4. Native applications, authentication generators, and generated APIs remain preview surfaces.

Amber CLI 2.0.4

Amber CLI 2.0.4 makes persistence part of the supported Amber V2 web-app path. A new application includes Grant ORM, SQLite, typed database settings, and Micrate-powered database commands by default.

Start a database-backed app

amber new pet_tracker --type web
cd pet_tracker
amber generate scaffold Pet name:string:required species:string:required adopted:bool
amber database migrate
amber watch

Open http://127.0.0.1:3000/pets/new. The generated resource includes a Grant model, request schema, HTML CRUD controller, ECR views, specs, resource route, and reversible SQL migration. SQLite keeps the first run self-contained; pass -d pg or -d mysql to amber new for a server database.

What changed

• Added Grant and the selected database driver to every generated web app.
• Made SQLite the default database and connected development, test, and production settings through config/database.cr.
• Embedded Micrate in amber database for migrations, status, rollback, redo, reset, and seeding.
• Promoted model, scaffold, and migration generation to the supported beta path.
• Corrected scaffold forms, optional fields, resource routes, and form-body handling so generated create and update requests persist successfully.
• Added a release smoke test that generates a Pet resource, migrates both test and development databases, runs its specs, boots the app, creates a Pet, and updates it through the generated HTML forms.
• Added a native Linux ARM64 release artifact and a Windows x86-64 generated-app compile gate.

Amber V2 native applications, generated authentication, and generated APIs remain preview surfaces in this release.

Amber CLI 2.0.3

Amber CLI 2.0.3 is the supported standalone CLI for Amber 2.0.0-beta.2. This patch brings the generated web application into the same visual and front-end language as the Amber V2 website.

Install

brew install amberframework/amber_cli/amber_cli
amber --version

Direct release assets are provided for Apple Silicon macOS and x86_64 Linux. Download the matching .tar.gz and .sha256 files and verify the checksum before installing amber and amber-lsp.

What changed

• New web applications open with a responsive Amber V2 starter page instead of the generic welcome screen.
• The starter carries Amber's warm paper palette, faceted-crystal motif, editorial type scale, status chips, and clear first-edit paths.
• The generated ECR layout now uses a browser-native import map and a local ES module entry point.
• CSS and JavaScript remain local to the application; the supported starter has no Node, npm, bundler, CDN, remote font, or UI-library requirement.
• Generator specs and the release smoke test verify the branded page, local stylesheet, import map, application specs, production build, and live HTTP responses.

Supported beta path

amber new my_app --type web
cd my_app
crystal spec
crystal build src/my_app.cr -o bin/my_app
amber watch

See the web-app guide and generator support table.

Model, scaffold, API-resource, auth, and native app generators remain preview surfaces in this release.

Amber CLI 2.0.2

Amber CLI 2.0.2 is the supported standalone CLI for Amber 2.0.0-beta.2.

Install

brew install amberframework/amber_cli/amber_cli
amber --version

Direct assets are provided for Apple Silicon macOS and x86_64 Linux. Download the matching .tar.gz and .sha256 files and verify the checksum before installing amber and amber-lsp.

What changed

• Web apps now pin amberframework/amber at 2.0.0-beta.2.
• The generated web app is ECR-only and uses typed V2 environment YAML.
• Personal fork, implicit Grant/Gemma, asset pipeline, and all-database-driver dependencies were removed from the core template.
• Static CSS and JavaScript use an explicit wildcard static route.
• Generated app specs no longer start the server or use invalid dynamic includes.
• Absolute destination paths resolve correctly.
• Dependencies install by default; --no-deps keeps offline/CI control.
• CLI and generator help label native and persistence-backed output as preview.
• Release CI rejects macOS binaries linked to [email protected] and exercises the complete generated web-app path on both supported platforms.

Supported beta path

amber new my_app --type web
cd my_app
shards install
crystal spec
crystal build src/my_app.cr -o bin/my_app
amber watch

See the web-app guide and generator support table.

Model, scaffold, API-resource, auth, and native app generators remain preview surfaces in this release.