Altair v0.2.1

Altair v0.2.1

The Phase 6 hardening wave, the redesigned website, and the end-to-end showcase demo. This is the last planned milestone before post-release work.

Highlights

• Sessions + flash + CSRF + auth — pluggable Altair::Session backed by an HMAC-SHA256 signed cookie store, one-request Flash, protect_from_forgery with constant-time token checks, and Altair::Auth::JWT (HS256) for stateless API auth — plus sign_in / sign_out / require_login / authenticate! helpers.
• File-driven configuration. .env / .env.<environment> and config/database.yml per-environment settings merged into config at boot.
• Multipart form parsing. File uploads arrive as Altair::HTTP::UploadedFile via params.upload("avatar"), with #save and #content.
• Security middleware set. SecurityHeaders (nosniff / SAMEORIGIN / referrer), RequestId (with request-scoped trace id), and opt-in Cors.
• Website redesign + new docs. Sessions, config, security and uploads guides; feature count bumped to 705 specs passing with Phase 6 complete.

Fixes

• Template form_for transpiler: helper actions with nested parens (e.g. form_for(post_path(post.id), ...)) and block forms no longer break the compile-time transpiler.
• altair update follows redirects: GitHub asset host redirects are now handled with bounded retries and timeouts.

Binaries

Standalone builds for Linux, macOS and Windows (amd64 + arm64), verified by SHA256SUMS. Install with curl -sSL https://.../install.sh | sh, then altair update.

See the CHANGELOG for the complete list.

Altair v0.2.0

Performance

• SQL statements are built once per connection (Record::Model + Connection#sql_template): find, find_by_* and insert cache their quoted statements instead of rebuilding them per call — the write path allocates half as much (frozen-GC harness, PostgreSQL: Item.create 2,033 → 964 B/op, Item.find 1,378 → 1,060 B/op).
• Route-lookup LRU cache: repeated paths collapse to a hash lookup (config.router_cache_size, default 1024) — measured ~10x on hot paths with zero per-request routing allocations.
• Route resolution is a single scan: matching and the 405 method list come from one pass; candidate lists merge without allocation.
• Lazy request parsing: query string, JSON body and the params bag parse on first access (bare GET: 784 → 368 B/op).
• Lock-free Record.connection steady path, parallel execution on boot, warm pool defaults, and bounded admission control (db_max_active_queries + db_admission_timeout) that parks excess load outside the pool.

Framework

• Controller hardening wave: before_action / after_action / skip_* callbacks with inheritance, controller-level rescue_from, respond_to, JSON-object rendering, redirect_back, request.format, JSON request bodies, clean head, chunked stream, segment-based route index, find_each keeping filters + preloaders, COUNT(*) relation counting, development N+1 detector, granular on_query_event instrumentation, Connection#pool_stats.

Benchmarks

• New committed benchmark harness (examples/benchmark_k6) vs Express and Fiber on identical PostgreSQL CRUD under k6: 1,000 VUs / 60 s sustained, equal 200-connection budget, warm-up excluded from measurement.
• Write (POST /items): Altair 13,167 req/s (1.81x Express) — write p99.9 145.9 ms (7x tighter than Express), write max 201.5 ms, the best of all three.
• Read (GET /items/:id): Altair 14,687 req/s (1.91x Express), p99.9 318.4 ms / max 479.6 ms.
• Zero failed requests in all six runs. Full report, methodology and the tail-latency investigation in the harness README; the website gained a dedicated Benchmarks page.

CLI / Release infrastructure

• altair update (self-update with SHA-256 verification, --check, --force), app-context command delegation from any directory, one-command installers for Linux/macOS/Windows with checksum enforcement, altair install onto PATH.

v0.1.2

Altair v0.1.2

Two big quality-of-life improvements for the CLI in this release.

What's new

altair update — self-update from the command line

The binary can now update itself:

altair update          # update to the latest release
altair update --check  # exit 0 when current, 1 when an update is available
altair update --force  # reinstall even when already up to date

It downloads the platform binary from the latest GitHub release, verifies
its SHA-256 digest against the published SHA256SUMS, and swaps it in
atomically via a temporary file — no partial installs, no manual downloads.

App-context delegation — drop the bin/ prefix

altair server, altair routes, altair db:migrate and altair db:rollback
now work from any directory inside a project, subfolders included. The
global binary walks up to the nearest project root and forwards the command
to its launcher — an executable bin/altair when present, otherwise
crystal run bin/altair.cr for projects generated before the launcher
existed. The old Unknown command hint is gone.

Also in this release

• New Updating section in README.md and the CLI docs; new website page
  docs/update.html.
• Version bumped to 0.1.2.

Try it

curl -fsSL https://github.com/Arab-Open-Source/Altair/releases/latest/download/install.sh | sh

v0.1.1

Altair v0.1.1

The first full public release: the batteries-included web framework for
Crystal, end to end — foundation, router, controllers, views, ORM, CLI and
generators — together with the documentation site and one-command
installers for every platform.

The framework

Phases 0–5 ship with passing specs.

• Application core — a conventional Altair::Application subclass with
  typed per-environment config, singleton instance, rescue_from exception
  mapping, and a middleware pipeline (Logger + Static with path-traversal
  protection).
• Router — compile-time DSL (get/post/put/patch/delete,
  namespace, resources, root) with typed references to controller
  actions, path helpers as real methods, 404/405 handling, and a wave of
  post-launch additions:
  • resources blocks with member / collection routes and nesting
  • singular resource :profile (six id-less routes, no-argument helpers)
  • glob segments (/files/*path) and permanent redirect "/old", to: "/new"
  • per-route constraints: { id: /\d+/ } and the implicit .{ext} format
    suffix (/posts/5.json → params["format"])
  • smarter pluralization (notes, courses, addresses)
• Controllers — per-request instances, render (html/text/json),
  redirect_to, head, merged typed params (fetch/require/permit),
  send_file / stream, _method override.
• Views — compile-time .ecr templates with typed locals (a wrong local
  is a compile error), auto-escaping by default, layouts with yield,
  partials, helpers (including block components), a form builder, and an
  optional htmx layer.
• Smart error pages — debug-mode 404 with route suggestions, 405 with
  _method hints, and full 500 diagnostics; plain text in production.
• Request hardening — a 2 MB body limit (configurable) answers 413
  before the body is read.

Altair::Record — the ORM

Shipped across three waves:

• Foundation — adapter interface with SQLite3 and PostgreSQL, pooled
  connections, transactions and savepoints, migrations DSL + runner with a
  schema_migrations table and auto-regenerated db/schema.cr, on_query
  instrumentation.
• Models — table macro with compile-time typed attributes, CRUD,
  find_by_* finders, pluck, validations (presence, length, numericality,
  uniqueness, inclusion/exclusion, format, confirmation), automatic
  timestamps, and the eight save/create/update/destroy callbacks.
• Associations — belongs_to / has_many / has_one with batched
  eager loading via Relation#includes, dependent: :destroy /
  :delete_all / :nullify, plus dirty tracking with partial updates and
  JSON / decimal / bigint columns.
• Performance and safety — lock-free connection lookup, fiber-safe
  transaction state, single-statement saves for callback-free models, and a
  configurable pool warm-up; the contract suite runs against both SQLite and
  PostgreSQL.

CLI, generators and installers

• altair new <name> scaffolds a runnable project (src/, db/,
  public/, bin/altair + bin/altair.cmd).
• altair g model / g migration / g controller and the full
  altair g scaffold Post title:string body:text write ready-to-edit
  files with a seeded db/schema.cr.
• Inside a project, bin/altair server, bin/altair routes,
  bin/altair db:migrate and bin/altair db:rollback drive the app.
• altair install copies the binary onto your PATH (~/.local/bin
  on Unix, %USERPROFILE%\.altair\bin on Windows), prints its SHA-256
  digest, is idempotent and refuses to clobber an unrelated file without
  --force.
• Distributed installs — release.yml (triggered by a v* tag) builds
  Linux/macOS/Windows binaries (amd64 + arm64) with SHA256SUMS, and the
  fail-safe scripts/install.sh / install.ps1 / install.cmd download,
  verify and install in one command.

Website

A documentation site at https://arab-open-source.github.io/Altair/ —
landing page, install, usage, features and CLI reference — generated from
markdown in website/ and deployed to GitHub Pages.

Fixes

• shards install inside a generated project no longer fails looking for a
  prebuilt executable.
• altair new writes a real executable bin/altair launcher, so the
  documented commands work exactly as written.
• Running app commands through the global binary inside a project now points
  you at the launcher instead of a bare Unknown command.

Try it

curl -fsSL https://github.com/Arab-Open-Source/Altair/releases/latest/download/install.sh | sh
altair new blog
cd blog && shards install && altair server

v0.1.0

Altair v0.1.0

The initial release — Altair, a batteries-included web framework for
Crystal, built end to end: foundation, router, controllers, views, ORM,
CLI and generators, all shipping with passing specs.

The framework

• Application core — Altair::Application subclass with typed
  per-environment config, singleton instance, a boot banner, and a
  top-level error boundary.
• Router — compile-time DSL (get/post/put/patch/delete,
  namespace, resources, root), typed references to controller
  actions, generated path helpers as real methods, 404/405 handling, glob
  segments (/files/*path) and a smarter resources pluralizer.
• Controllers — per-request instances, render (html/text/json),
  redirect_to, head, merged typed params (fetch/require/permit),
  send_file / stream, _method override, and rescue_from exception
  mapping.
• Views — compile-time .ecr templates with typed locals, auto-escaping
  by default, layouts with yield, partials, helpers (incl. block
  components), a form builder, and an optional htmx layer.
• Smart error pages — debug-mode 404 with route suggestions, 405 with
  _method hints, and full 500 diagnostics; plain text in production.
• Request hardening — a 2 MB body limit answers 413 before the body
  is read.
• Middleware pipeline — use-based stack with Logger and Static
  (path-traversal protected).

Altair::Record — the ORM

• Wave 1 — foundation: adapter interface with SQLite3 and PostgreSQL,
  pooled connections, transactions and savepoints, migrations DSL + runner
  with schema_migrations and auto-regenerated db/schema.cr, on_query
  instrumentation.
• Wave 2 — models: table macro with typed attributes, CRUD,
  find_by_* finders, pluck, validations (presence, length, numericality,
  uniqueness, inclusion/exclusion, format, confirmation), automatic
  timestamps, and the eight save/create/update/destroy callbacks.
• Wave 3 — associations: belongs_to / has_many / has_one with
  batched eager loading via Relation#includes, dependent: handling.
• The adapter contract suite runs against both SQLite and PostgreSQL.

CLI, generators and installers

• altair new <name> scaffolds a runnable project (src/, db/,
  public/, launchers for POSIX and Windows).
• altair g model / g migration / g controller and the full
  altair g scaffold Post title:string body:text write ready-to-edit
  files with a seeded db/schema.cr.
• altair install copies the binary onto your PATH, prints its
  SHA-256 digest, is idempotent and refuses to clobber an unrelated file
  without --force.
• Distributed installs — a release pipeline builds Linux/macOS/Windows
  binaries (amd64 + arm64) with SHA256SUMS, and the fail-safe
  scripts/install.sh / install.ps1 / install.cmd download, verify and
  install in one command.

Benchmarks

k6 comparison scripts and results for Altair against Express and Fiber, a
Rails-vs-Altair staging harness, and the tail-latency investigation
write-up (examples/benchmark_k6, examples/rails-vs-altair).

Try it

shards build altair
./bin/altair new blog
cd blog && shards install && ./bin/altair server