# Glacier
A batteries-included web framework for Rust, inspired by Rails, Phoenix and
Laravel. Controllers, models and tests are written in `.glacier`, an
Elixir-flavoured syntax that compiles to Rust at build time. Routes and
anything else are Rust, and Rust works everywhere `.glacier` does.
```elixir
# src/controllers/posts_controller.glacier
controller Posts do
def index do
posts = Post.order(inserted_at: :desc)!
render posts, title: "Posts"
end
def create(ctx) do
post = Post.build(ctx.params())
if post.save()! do
redirect post, notice: "Post created."
else
render :new, post, title: "New post", status: 422
end
end
end
```
```elixir
# src/models/post.glacier
model Post do
field title: String, required
field body: Option<String>
field published: bool
end
```
```rust
// src/routes.rs
glacier::routes! {
pipeline browser = Pipeline::browser();
scope "/" through browser {
get "/" => Pages::home, as home;
resources "/posts" => Posts {
// /posts/:post_id/comments, with post_comments_path(post_id)
resources "/comments" => Comments, only [index, create];
}
}
}
```
```html
{% props posts: Vec<Post> %}
<h1>Posts</h1>
{% for post in posts %}
{{ link_to(&post.title, post) }}
{% end %}
```
These are taken from `examples/hello`, which is generated by
`glacier new` and `glacier generate scaffold`.
## Why
- **Rust is fast.** Compiled ahead of time, no garbage collector, async on
hyper and Tokio, so an app gets a lot out of a small server.
- **Code should be written for humans to read.** AI writes more code than
ever (it wrote much of this repository), and someone still has to review
it. Rust is powerful but not the easiest language to read. Rails has
always put readability for people first; Glacier brings that to Rust.
`.glacier` reads like Elixir or Ruby, and compiles to Rust, so you can
drop to Rust syntax whenever you need it.
- **The compiler is the first reviewer.** Templates, routes, path helpers
and query columns are all compiled, so a typo is a build error rather
than a 500 in production. Errors point at your `.glacier` line, which
keeps the fix loop short for people and for AI agents alike.
- **Conventions mean less to read.** Every app has the same layout, and the
generators write controllers, models, views and their tests the same
way, so code is where you expect it and a review starts from what's
different.
- **One binary to deploy.** A release build is a single executable with
its templates, migrations, config and static files built in: copy it to
a server, point it at a database, and run it. No interpreter or runtime
to install, quick to start, and small enough to run many apps on one
server.
- **Rust's ecosystem, not a new one.** Everything compiles to ordinary
Rust, so cargo, crates.io, rust-analyzer and clippy all keep working.
`.glacier` is a layer you can step out of, not a separate language.
## Models, Active Record style
Models declare their fields, validations, associations, scopes, methods and
callbacks in one place:
```elixir
# src/models/post.glacier
model Post do
field title: String, required, length(max: 200)
field slug: String, unique, format: "^[a-z0-9-]+$"
field views: i32, numericality(greater_than_or_equal_to: 0)
field status: enum(draft, published), default: :draft
belongs_to :author
has_many :comments
scope published, where(status: :published)
scope by(author_id: i64), where(author_id: author_id)
def excerpt(self) -> String do
self.title.chars().take(140).collect()
end
def publish(self) do
self.update(status: :published)!
end
before_save do
self.slug = self.title.to_lowercase().replace(" ", "-")
end
end
```
and records work like Rails' Active Record:
```elixir
post = Post.new(title: "Hello")
post.title = "Hello, world"
post.save()! # true, or false with post.errors_on("title")
post.update(status: :published)! # in place; only changed columns are written
Post.where(status: :published, author_id: id).order(inserted_at: :desc)!
Post.published().by(id).limit(5)! # scopes chain
Post.find_by(slug: "hello")!
Post.exists(title: "Hello")!
Post.order(:title).pluck(:title)!
Post.where(published: true).sum(:views)! # also average, minimum, maximum
Post.group(:status).count()! # [("draft", 3), ("published", 5)]
Post.join(:author, name: "Ada").joins(:comments).distinct()!
Post.where(status: :draft).update_all(status: :published)!
post.changed("title") # dirty tracking; post.was("title")
post.destroy()! # with before_destroy/after_destroy
```
The keyword forms compile to typed column closures, so `where(titel: …)` is
a build error, not a runtime one. Every model also has the Ecto-style
changeset API (`Post.create(params)` returning `Saved`/`Invalid`), and
models can be plain Rust (`#[glacier::model]`, `#[glacier::scopes]`,
`#[glacier::enumeration]`, `impl Callbacks`). To share the database with
other libraries, `repo.postgres_pool()` and `glacier::sqlx` hand over the
sqlx pool, e.g. to SeaORM.
## JSON APIs and serializers
Serializers give a model its JSON shape, as active_model_serializers does
for Rails:
```elixir
# src/serializers/country_serializer.glacier
serializer CountrySerializer do
attributes :id, :iso_code, :name
attribute :label, format!("{} ({})", object.name, object.iso_code)
has_many :installations # every column, or serializer: InstallationSerializer
end
```
```elixir
# src/controllers/countries_controller.glacier
def index(_ctx) do
countries = Country.preload(:installations)!
json countries, each_serializer: CountrySerializer # {"countries": [...]}
end
```
`json` also takes `serializer:` for one record, `root:` (a key, or `false`),
and `status:`. Keys come out in the order written. Models can map an
existing Rails schema: `model Country, timestamps: false`, `field id: i32`,
and `has_many :installations, through: :countries_installations`.
Settings kept in a JSON column read like fields, as Rails'
`store_accessor`: `store :cache do field timezone: String, default:
"Europe/London" end` gives `info.timezone()`.
Preloads nest, as Rails' `includes`, one query per level:
`Post.preload(:author, comments: [:author, likes: :user])`.
`glacier::pagination::Page` reads `page`/`per_page` and `json posts,
paginate: (page, total)` adds api-pagination's `Link`, `Per-Page` and
`Total` headers. `Decimal` fields hold `numeric` columns exactly and
render as Rails renders a `BigDecimal` (`"50.0"`), and
`glacier::serialize::set_time_format` switches timestamps to Unix seconds
for apps that render them that way.
Associations take `order: :position`, and a model's
`default_scope order(:position).preload(:faq_items)` applies to every
query of it (`FaqSection.unscoped()` skips it).
The `glacier::i18n::Locales` middleware takes the locale from
`params[:locale]`, as Rails apps often do, and `locale()` reads it:
```elixir
faqs = FaqSection.where(locale: locale())!
```
`glacier::i18n::load("config/locales")` reads a Rails app's locale YAML,
and `t("versions.ios.warning")` translates in the current locale.
`JsonErrors::body(|status| …)` gives a pipeline's error responses the
app's own JSON shape, as a Rails `rescue_from` does. `unique` checks with a
query before writing, as Rails' `uniqueness` does, so it works without an
index, and takes a scope: `unique(scope: :platform)`.
Tests against an existing schema can use a Postgres test database loaded
from the Rails app's `structure.sql`; each test then runs in a
transaction that is rolled back. Factories skip the fields a test sets,
as FactoryBot does, so `insert(FaqItem, faq_section_id: id)` inserts no
extra section.
## Authentication
`glacier generate authentication` writes sign up, sign in and sign out into
the app, as Rails' `generate authentication` and Phoenix's `phx.gen.auth`
do: `User` and `Session` models with migrations, sessions and registrations
controllers, their pages and tests, and `src/authentication.rs`, which
finds who's signed in and adds an `authenticated` pipeline. It's ordinary
app code to read and change, not a library to configure:
```elixir
# src/models/user.glacier (generated)
model User do
field email_address: String, required, unique
field password_digest: String, protected
field password: Option<String>, virtual
has_many :sessions
def authenticate_by(email_address: &str, password: &str) -> Option<User> do
user = User.find_by(email_address: User.normalize_email(email_address))!
digest = user.as_ref().map(fn u -> u.password_digest.as_str() end)
if glacier::auth::verify_password(password, digest) do
user
else
None
end
end
...
end
```
```rust
// Routes for signed-in users only:
scope "/" through browser, authenticated {
get "/account" => Accounts::show, as account;
}
```
Passwords are hashed with Argon2id, and session tokens are random, with
only their SHA-256 digest stored. `--api` writes JSON endpoints that return
a token for `Authorization: Bearer …` instead of using the session cookie.
`glacier::storage::S3Signer` makes presigned S3 URLs (AWS Signature V4, as
Active Storage and Paperclip hand out), and
`glacier::response::escape_html_entities_in_json(true)` writes `<`, `>` and
`&` in JSON as Rails does by default.
Authorisation rules are the app's own methods, as Laravel's gates are:
`authorize report.editable_by(&user)!` answers `403 Forbidden` unless the
rule allows it.
An existing app's users can sign in too: `glacier::auth::verify_password`
checks the bcrypt hashes Devise and `has_secure_password` store, as well as
Argon2. `glacier::middleware::Throttle` limits requests per key (an email,
an IP) as Rack::Attack and Rails 8's `rate_limit` do, and
`ctx.remote_ip()` finds the client behind trusted proxies as Rails does.
An existing app's tokens work too: `glacier::auth::jwt` signs and checks
HS256 JSON Web Tokens exactly as Ruby's `jwt` gem does, so a Glacier app
can accept the tokens a Rails app issues (and the other way round) while
endpoints move across.
## Authorization
Rules are the app's own functions; by convention a policy per model, as
Laravel's:
```sh
glacier generate policy Post # src/services/post_policy.glacier
```
```elixir
service PostPolicy do
def update(user: &User, post: &Post) -> bool do
post.user_id == user.id
end
end
```
`authorize PostPolicy.update(user, post)` in an action answers `403` when
the rule says no. Put `VerifyAuthorized` on a pipeline and an action there
that answers without `authorize` (or `skip_authorization`, for a public
one) is an error outside production, as Pundit's `verify_authorized`.
## Background jobs
Jobs live in the database, as Rails' Solid Queue keeps them: queued in the
same transaction as the work that asks for them, run by workers that
`glacier server` starts, retried with backoff, and left marked failed after
their last attempt.
```sh
glacier generate job SendReport report_id:bigint # src/jobs/send_report.rs
```
```rust
// src/jobs/send_report.rs
#[derive(Serialize, Deserialize)]
pub struct SendReport {
pub report_id: i64,
}
impl Job for SendReport {
const NAME: &'static str = "send_report";
async fn perform(self) -> Result<()> {
// …
Ok(())
}
}
```
Queue one with `SendReport { report_id }.enqueue()!` (or `enqueue_in`), and
in tests run what's queued with `glacier::testing::perform_jobs()!`.
## How `.glacier` works
The app's `build.rs` compiles each `.glacier` file into ordinary Rust, line
for line, in a hidden, git-ignored `.glacier/` folder. `create` above
becomes:
```rust
// .glacier/controllers/posts_controller.rs (generated)
async fn create(ctx: Context) {
let mut post = Post::build(ctx.params());
if post.save().await? {
redirect!(post, notice: "Post created.")
} else {
render!(post; template = new, title = "New post", status = 422)
}
}
```
`src/` holds only what you write, and `controllers/mod.rs` and
`models/mod.rs` are one line each: `glacier::controllers!(pages, posts);`,
`glacier::models!(post);`. As in Rails, models need no import: controllers,
models, serializers and tests all see every model. `alias Serializers.X`
(or any `alias Module.Name`) brings in anything else.
- **Plain tools work.** `cargo build`, `cargo test` and clippy work
unchanged, and any crate from crates.io can be used.
- **Errors point at your file.** Compiler errors land on the `.glacier`
line, which is the same line number as the generated Rust.
- **Editor support.** `glacier lsp` proxies rust-analyzer, so hover,
go-to-definition and errors work in `.glacier` files, and formats them.
The [VS Code extension](https://github.com/glacierlabsltd/glacier-vscode)
adds highlighting and starts it; any editor with an LSP client can point
at `glacier lsp`.
- **One format.** `glacier fmt` (or `--check` in CI) lays out `.glacier`
files canonically.
- **Variables work as in Ruby.** `total = 0` binds a name; assigning to it
inside an `if` or loop updates it, rather than making a new one that ends
with the block. `(posts, total) = load()!` destructures.
- **Rust when you want it.** `.rs` and `.glacier` controllers mix in one
app, and `--dialect rust` makes the generators write plain Rust.
The dialect is an experiment.
## Tests in `.glacier`
Tests read the same way, ExUnit-style. Every generator writes them: the
scaffold writes `tests/controllers/posts_controller.test.glacier`,
`tests/models/post.test.glacier` and a factory in
`tests/factories/post.glacier`. The controller tests start:
```elixir
# Load a form first, as a browser would, for its CSRF token.
setup do
get "/posts/new"
end
test "rejects a post without title" do
res = post "/posts", params_for(Post), title: ""
assert res.status == :unprocessable_entity
assert res.body =~ "can't be blank"
end
test "deletes a post" do
post = insert(Post)
res = delete post
assert res.status == :see_other
assert get(post).status == :not_found
end
```
- **Every test gets a fresh, migrated database** and its own client, which
keeps cookies and the CSRF token like a browser, so there's no setup
code to repeat.
- **Factories** in `tests/factories/` give `insert(Post)` and
`params_for(Post)` valid fields to start from; override any per call.
Model tests check validations with
`assert errors_on(saved) =~ "title can't be blank"`.
- **Failures explain themselves** and point at the `.glacier` line:
```text
panicked at tests/controllers/pages_controller.test.glacier:4:3:
assertion failed: res.body =~ "is running on Rails"
expected to contain: "is running on Rails"
but was: "<!doctype html>…"
```
- `describe "…" do` groups tests, `test "…", skip: "why" do` skips one,
and `def` defines helpers (calls to them are awaited for you).
`tests/glacier.rs` declares them all with
`glacier::tests!(controllers::posts_controller, factories::post, models::post, …)`, so
they build into one test binary, named by folder
(`controllers::posts_controller::lists_posts`). Run them with `cargo test`, or
`glacier test` to see `.glacier` paths in failures.
Templates, routes and queries are all compiled, so a typo in a template
expression, a link to a missing route or a misspelled column is a build error,
not a 500.
## Status
Early, but proven on a real app: a production Rails 6.1 JSON API was
ported endpoint by endpoint, each checked byte for byte against Rails.
Glacier has a route table with Phoenix-style pipelines, nested resources,
constraints and generated path helpers; controllers with convention-based
rendering and compiled templates; JSON APIs with serializers
(`glacier new --api`); an Active Record-style ORM for Postgres and SQLite
(validations, callbacks, associations with `through`, `dependent`, `touch`
and nested attributes, joins and aggregates, changesets, migrations);
file uploads to disk or S3; an authentication generator; sessions, flash,
CSRF and CORS; config per environment; and the basics for production: a
`/up` health check, JSON logs, and traces of every request and query,
which the optional `glacier-otel` crate exports to any OpenTelemetry
backend; and background jobs in the database. See
[CHANGELOG.md](CHANGELOG.md). Live views come next.
## Layout
| `crates/glacier` | The framework (`glacier-web` on crates.io, used as `glacier`): server (on hyper), router, controllers, middleware, views, sessions, the `db` ORM, testing |
| `crates/glacier-macros` | `routes!`, `controllers!`, `models!`, `serializers!`, `tests!`, `#[controller]`, `#[model]`, `#[scopes]`, `#[enumeration]`, `render!`, `views!`, `html!`, `config!`, `static_files!`, `#[derive(Template)]`, `#[derive(Model)]`, `#[glacier::main]` |
| `crates/glacier-dialect` | The `.glacier` transpiler and the build-script compiler |
| `crates/glacier-otel` | Optional OpenTelemetry (OTLP) export of Glacier's traces |
| `crates/glacier-inflect` | Pluralizing and case conversion, shared by the crates |
| `crates/glacier-cli` | The `glacier` command (`glacier-web-cli` on crates.io): `new`, `server`, `build`, `test`, `fmt`, `compile`, `lsp`, `routes`, `db`, `generate`, `secret` |
| `examples/hello` | Exactly what `glacier new` + `glacier generate scaffold Post …` produce: controllers, models and tests in `.glacier`, compiled at build time by `build.rs` |
## Getting started
Glacier needs Rust 1.94 or later. Install the `glacier` command from
crates.io, then make an app:
```sh
cargo install glacier-web-cli
glacier new blog && cd blog
glacier generate scaffold Post title:string body:text:optional published:boolean
glacier generate model Tag name:string # or just a model, with its tests
glacier generate controller Reports summary # or just a controller, with its tests
glacier db migrate
glacier server # rebuilds on every change; visit /posts
glacier test # the generated tests (or cargo test)
glacier new shop-api --api # a JSON API: no views or CSRF, errors as
# JSON; scaffolds there are JSON controllers
```
New apps depend on `glacier-web` from crates.io (used in code as
`glacier`).
## Working on Glacier
From a checkout, `glacier new` makes apps that use the checkout's crates:
```sh
cargo install --path crates/glacier-cli
cargo build -p glacier-web-cli # or just build: target/debug/glacier
cd examples/hello && ../../target/debug/glacier db migrate && ../../target/debug/glacier server
# http://127.0.0.1:4000/posts
cargo test --workspace
GLACIER_TEST_POSTGRES_URL=postgres://$USER@localhost/glacier_framework_test cargo test --workspace
```
See [CONTRIBUTING.md](CONTRIBUTING.md) before sending changes.
## Licence
Glacier is released under the [MIT licence](LICENSE), copyright Glacier
Labs Ltd. See [CONTRIBUTING.md](CONTRIBUTING.md) to get involved.