is the outermost tag AND a child
var bad =
var alsoBad =
// CORRECT — open with a different tag, then nest freely
var good =
// CORRECT — once the tree starts with a different tag, the
// original tag can appear at any depth below it
var fine =
Deeply nested same tags work here
```
**Pitfall:** this bites the common JSX pattern of a wrapper `
` inside a
`
` (row, then column). If you need the same tag twice, change the
outermost wrapper or extract the inner one into a component method (see
section 4).
Two more parser quirks to unlearn from JSX:
- **Mismatched closing tags are not validated.** Only the outermost closing
tag is matched. `
Hello
` compiles and is served verbatim —
the browser auto-closes the `
` at render time. Write well-formed HTML
yourself; there is no compiler checking your balance.
- **Tag names are restricted.** Lowercase, start with a letter, only letters,
numbers, and hyphens. `` and `` are compiler
errors. PascalCase component names are a JSX thing — see section 4.
---
## 2. Map Callback Restrictions
In JSX you write `{items.map(item => {item} )}` and the arrow function
can hold any logic. In Bialet the `map` callback is a **single Wren
expression** — the inline HTML string itself:
```wren
var items = ["Apple", "Banana", "Cherry"]
var html = {{ items.map { |item| {{ item }} } }}
// Output:
```
The two restrictions that will trip you up:
### No statements inside the callback
You cannot declare a variable or write multiple lines of Wren inside `map`:
```wren
// WRONG — multiple statements inside the map callback
{{ tasks.map { |task|
var icon = task.finished ? "✓" : "○"
{{ icon }} {{ task.description }}
} }}
```
If you need pre-computed values, compute them **before** `map`, or add a
computed property to your model class:
```wren
var tasks = Tasks.list().map { |t| t.withIcon } // pre-process the list
return {{ tasks.map { |t| {{ t.icon }} {{ t.description }} } }}
```
### The body must start on the line after `{`
A multi-line block whose body is not a single expression on the `{` line
returns `null` silently — the output is empty and nothing tells you why:
```wren
// WRONG — the callback body breaks onto its own line, returns null, renders empty
return {{ items.map { |item|
{{ item }}
} }}
// CORRECT — the expression starts on the {{ line; the HTML string
// itself may span many lines
return {{ items.map { |item|
{{ item.description }}
} }}
```
### Empty lists render empty
`map` over an empty list produces nothing. In JSX you'd conditionally render a
fallback; in Bialet you pair `map` with `&&`:
```wren
return
{{ tasks.map { |task| {{ task.description }} } }}
{{ tasks.count == 0 && }}
```
---
## 3. Interpolation Rules
JSX interpolates with `{expr}`. Bialet uses `{{ expr }}` — the extra brace is
what makes it valid Wren inside an HTML string. The rules differ more than the
syntax:
### `{{ }}` is the only interpolation point
Interpolation happens only inside `{{ }}`. A bare `{expr}` is not a template
expression — inside an HTML string it is literal text, and outside one it is
Wren map syntax.
### Values are escaped by default
This is the biggest safety win over JSX (where you must remember
`dangerouslySetInnerHTML`). Plain values — user input, database rows, URL
parameters — are HTML-escaped automatically:
```wren
var userInput = ""
var safe = {{ userInput }}
// Renders: <script>alert('xss')</script>
```
### Line breaks follow Wren, not JSX
A `{{ }}` expression can span lines, but an infix operator must end its line.
A leading operator is a parse error:
```wren
// CORRECT — operators end each line
return {{
showClear &&
}}
// WRONG — the operator starts a line
return {{
showClear
&&
}}
```
### Interpolation depth is limited
Nesting is capped at 9 levels of `{{ }}`. Deeply nested JSX interpolations
must be flattened.
### No expressions in string values
JSX lets you write `className={`btn ${active ? 'on' : ''}`}` — a template
literal inside an attribute. Bialet does not support string interpolation
into attribute values. Compute the string first, then interpolate the result:
```wren
// WRONG — no template literals
...
// CORRECT — compute the class, then interpolate it
var cls = "btn " + (active ? "on" : "")
...
```
For simple two-way choices, the ternary inside `{{ }}` is fine:
```wren
```
---
## 4. Component-as-Method Pattern
JSX has components: functions that take props and return JSX, composed via
`
{{ title }}
{{ body }}
}
layout(content) {
{{ content }}
}
}
```
Compose by passing markup into methods, not by nesting tags:
```wren
// index.wren
import "_template" for Template
return Template.new().layout(
Template.new().card("Hello", World
)
)
```
Because the method returns a plain string, the same-tag nesting rule applies
across the boundary: if a component's outermost tag would repeat under a
caller's outermost tag, the parser rejects it. `card()` returning an
`` inside a page whose outermost tag is also `` fails —
widen one of them.
**Pitfall:** instance methods need `new()`. `Template.layout(...)` looks for
a static method and fails. Always instantiate first.
**Pitfall:** a method body is an expression body only when the expression
starts on the same line as `{`. A statement body on the following line
returns `null` silently — the component renders as empty with no error.
Keep the opening HTML tag on the method's first line.
---
## 5. Raw HTML Security Footguns
Bialet escapes by default — the safety flip of JSX's default-raw model. The
footguns are the ways you can accidentally defeat that default and re-open
the XSS holes `dangerouslySetInnerHTML` created for you.
### Footgun 1: `.safe` is the opposite of what you expect
`.safe` marks a string as trusted markup. Inside `{{ }}`, interpolation
already escapes, so `{{ userInput.safe }}` escapes the text **twice**
(`<` instead of `<`) — the raw HTML you meant is shown as text.
Drop `.safe` from templates entirely.
### Footgun 2: `.raw` / `HtmlNode` skip all sanitization
To render a runtime string as markup you must mark it safe, and that is an
assertion, not a sanitizer:
```wren
var html = "bold ".raw
{{ html }}
// rendered as written
{{ "bold " }}
// escaped: <b>bold</b>
```
`.raw`, `HtmlNode.new(...)`, and `HtmlNode` values are inserted verbatim —
no escaping, no scrubbing of `")
// WRONG — javascript: links are not filtered
var link = Markdown.html("[x](javascript:alert('xss'))")
```
Render only Markdown you trust.
### Footgun 4: interpolation inside `")` emits a live `"
var safe = {{ userInput }}
// Renders: <script>alert('xss')</script>
```
Escaping replaces `&`, `<`, `>`, `"`, and `'` with their HTML entities. The
standalone helper `Util.htmlEscape(str)` returns the same result:
```wren
var escaped = Util.htmlEscape(userInput)
```
> ⚠️ Pitfall: **Do not add `.safe` inside `{{ }}`.** Since interpolation
> already escapes, `{{ userInput.safe }}` escapes the text twice
> (`<` instead of `<`). Drop `.safe` from templates.
### Intentionally raw HTML
Values that are already rendered HTML are marked with an `HtmlNode` and are
left untouched by interpolation:
- **HTML string literals** — `...
` evaluates to an `HtmlNode`.
- **Nested `{{ }}` blocks** — their result is an `HtmlNode`, so nesting
`{{ outer }}` around inner markup does not double-escape it.
- **`.raw`** — `"bold ".raw` marks a string as safe HTML.
- **`HtmlNode.new(...)`** — wrap a runtime string explicitly.
```wren
var userText = ""
var card =
var safeMarkup = "raw ".raw
{{ userText }}
// escaped
{{ card }}
// rendered as written
{{ safeMarkup }}
// rendered as written
// A string that really does contain markup must be marked safe:
var html = "bold ".raw
{{ html }}
```
Sequences are flattened by interpolation, so building a list of fragments
with `map` escapes each item's user data while keeping the surrounding
markup:
```wren
var items = ["a ", "b"]
{{ items.map{|x| {{ x }} } }}
// <b>a</b> b
```
> ⚠️ Pitfall: `HtmlNode` and `.raw` assert that the string is already safe.
> They do not sanitize JavaScript, CSS, or URLs. Never interpolate untrusted
> input into a `")
// WRONG — javascript: links are not filtered
var link = Markdown.html("[x](javascript:alert('xss'))")
```
Render only Markdown you trust, or sanitize the output before serving it. See
the [Markdown](markdown.md) guide for the full syntax and security notes.
## SQL Injection
Backtick Query objects use **prepared statements** with `?` placeholders.
The query string and the values are sent to SQLite separately, so values
cannot change the structure of the SQL.
```wren
// CORRECT — parameterized
`SELECT * FROM users WHERE name = ? AND active = 1`.fetch(name)
// CORRECT — multiple parameters
`INSERT INTO messages (text, session) VALUES (?, ?)`.query(msg, Session.id)
// WRONG — never build SQL from strings
`SELECT * FROM users WHERE name = '%(name)'`.fetch
```
You cannot concatenate or interpolate into a backtick Query object — the
compiler rejects it. That constraint removes the most common injection path
entirely. Stay inside it.
Two places tempt people out of it:
- **Dynamic `ORDER BY` columns.** Column names cannot be placeholders. Use
the `order()` method with an allow-list of column names:
```wren
`SELECT * FROM products`.order("price", "ASC",
["price", "name", "createdAt"], 50).fetch
```
- **`LIMIT` / `OFFSET`.** These accept only integers. Parameterize them —
never concatenate user input:
```wren
`SELECT * FROM products LIMIT ? OFFSET ?`.fetch([limit, offset])
```
> ⚠️ Pitfall: database values come back as strings. Before using one as a
> number, convert with `Num.fromString(...)` or `query.num`. This is a
> correctness concern, but it also stops "it works when I type a number"
> bugs from becoming injection-adjacent string handling.
See the [Database](database.md) and [Advanced Routing](advanced-routing.md) guides for more
Query examples.
## CSRF Protection
Bialet ships built-in CSRF tokens via `Session`. A token is generated per
session, stored server-side, and rendered as a hidden form field. On
submission, the token in the request is compared against the stored token
using `Util.secureEquals` — a constant-time comparison that does not leak
timing information.
```wren
var session = Session.new()
var verified
if (Request.isPost) {
verified = session.csrfOk
if (verified) {
`INSERT INTO messages (text) VALUES (?)`.query(Request.post("msg") || "")
}
}
return
```
- `Session.csrf` returns a `👋 Hello World ")
// Multiple chained assertions
Test.get("/hi")
.status(200)
.contains("Hello")
.contains("World")
.notContains("Goodbye")
```
### Security and Negative Assertions
```wren
// From _tests/password.wren - test what should NOT be present
Test.post("/password", {"password": "abc", "password-check": "xyz"})
.status(200)
.notContains("The passwords are the same") // Should not contain success message
// From _tests/assertions.wren
Test.get("/hi")
.status(200)
.notContains("Error")
.notContains("Failed")
```
### Form Testing
```wren
// From _tests/password.wren
Test.post("/password", {"password": "123", "password-check": "123"})
.status(200)
.contains("The passwords are the same")
Test.post("/password", {"password": "123", "password-check": "321"})
.status(200)
.contains("The passwords are different")
```
### Complete Test Examples
```wren
// From _tests/assertions.wren - comprehensive testing
Test.get("/hi")
.status(200)
.equals("👋 Hello World ")
Test.post("/password", {"password": "test123", "password-check": "test123"})
.status(200)
.contains("The passwords are the same")
.contains("Hash:")
```
## Best Practices
### Use Appropriate Assertion Methods
```wren
// ✅ Good - specific assertions
Test.get("/health").equals("OK")
Test.apiGet("/users").jsonContains("id")
// ❌ Avoid - too generic
Test.get("/health").contains("OK") // Could match "NOT OK"
```
### Security Testing
Always check that sensitive data isn't exposed:
```wren
// Ensure passwords/keys not in responses
Test.get("/public/user")
.notContains("password")
.jsonNotContains("ssn")
.jsonNotContains("api_key")
```
### Use Custom Assertions for Complex Logic
```wren
// Instead of manual Fiber.abort()
var data = Test.apiGet("/stats").json()
Test.assert(data["active"] > data["inactive"], "More active expected")
Test.assert(data["total"] == data["active"] + data["inactive"], "Count mismatch")
```
### Chain Related Assertions
```wren
// Group related checks together
Test.apiPost("/users", {"name": "Alice"})
.status(201)
.jsonContains("id")
.jsonContains("createdAt")
.jsonEquals("name", "Alice")
.jsonEquals("active", true)
```
### Test Both Success and Failure Cases
```wren
// Success case
Test.post("/login", {"user": "admin", "pass": "correct"})
.status(200)
.contains("Welcome")
// Failure case
Test.post("/login", {"user": "admin", "pass": "wrong"})
.status(401)
.contains("Invalid credentials")
```
## Database Isolation
Tests run against a **temporary database file** that is created fresh for each test run:
1. A temporary database file is created
2. Migrations are automatically run (`_migration.wren` or `_app/migration.wren`)
3. `_tests/_init.wren` runs (if exists)
4. Test files execute
5. Temporary database is deleted
This ensures tests don't pollute your development or production database.
## Complete Example
**Application file:** `hi.wren`
```wren
return 👋 Hello World
```
**Test file:** `_tests/hi.wren`
```wren
Test.get("/hi")
.status(200)
.contains("Hello World")
```
**Run tests:**
```bash
$ bialet -T
Running tests in _tests...
✓ hi.wren (5ms)
Summary:
Total Tests: 1
Passed Tests: 1
Failed Tests: 0
Skipped Tests: 0
Elapsed Time: 5ms
```
A failing assertion reports the file and the `Fiber.abort` message under it:
```bash
$ bialet -T
Running tests in _tests...
✗ hi.wren
Expected code to be 200 but was 500
Summary:
Total Tests: 1
Passed Tests: 0
Failed Tests: 1
Skipped Tests: 0
Elapsed Time: 20ms
```
## Exit Codes
- `0`: All tests passed
- `1`: One or more tests failed
This makes it easy to integrate with CI/CD pipelines. `-q` drops the colors
and per-test lines down to a single summary line plus a `### FAIL` block per
failure -- friendlier for CI logs:
```bash
$ bialet -T -q
1 of 1 tests failed in 20ms
### FAIL _tests/hi.wren:2 - hi
Expected code to be 200 but was 500
```
```yaml
# GitHub Actions example
- name: Run tests
run: bialet -T -q
```
## How It Works
1. **Request Building**: The `Test` class builds an HTTP request (method, headers, body)
2. **Internal Routing**: Instead of making actual HTTP calls, the test runner directly invokes the Wren handler
3. **Response Capture**: The response (status, headers, body) is captured and wrapped
4. **Assertions**: Each assertion checks the response and reports failures
5. **Database**: All database operations happen on a temp DB, isolated from your main data
This approach is fast (no network overhead), reliable (no port conflicts), and safe (isolated database).
# Deployment
Bialet is a single binary — copy it to your server alongside your `.wren`
files and you're deployed. This guide covers setting up a production-ready
environment with a reverse proxy, systemd, and Docker.
## Why a Reverse Proxy?
Bialet speaks **HTTP/1.0** and does not support HTTPS natively. Running it
behind a reverse proxy (nginx, Apache, or Caddy) gives you:
- **TLS termination** — HTTPS for your users
- **HTTP/1.1 or HTTP/2** between the client and the proxy
- **Static file caching and gzip** — the proxy can compress and cache assets
- **Security** — Bialet only needs to listen on `127.0.0.1`, not the public
internet
You *can* expose Bialet directly with `-h 0.0.0.0`, but this is not
recommended for production.
Bialet is **single-threaded per worker**: each process accepts and serves one
connection at a time, in a blocking loop. A request that arrives while the
worker is busy waits in the kernel's listen queue, so its latency is the
duration of the request in front of it. That is milliseconds for typical CRUD
pages, and the built-in header/body deadlines stop a stalled client from
holding the worker forever. For more concurrency, run several workers behind
the proxy (see [Scaling](#scaling-multiple-workers-on-one-host)).
The worker's listen backlog is 10, so a burst larger than that can be refused
before the worker ever accepts it. The proxy holds the burst in its own event
loop and feeds the worker only as it frees up — one more reason not to expose
Bialet directly.
The proxy is therefore not just for TLS — it is the layer that absorbs slow
clients, connection churn, and request buffering, and, when you scale, the
load balancer. Treat the proxy as part of your security posture, not a
convenience (see [Security](security.md) and the hardening section below).
## Scaling: Multiple Workers on One Host
One worker serves one request at a time, but that is a queueing limit, not a
hard ceiling. If 30 ms of requests are queued in front of yours, you wait
30 ms. For a typical CRUD page that is invisible; for a page that runs a slow
report query, every request behind it waits for the duration of that query.
When that matters, run several Bialet processes against the same app directory,
each on its own port, and let the proxy load-balance between them:
```bash
bialet -p 7001 -w /www/example.com
bialet -p 7002 -w /www/example.com
bialet -p 7003 -w /www/example.com
```
nginx:
```nginx
upstream bialet {
server 127.0.0.1:7001;
server 127.0.0.1:7002;
server 127.0.0.1:7003;
}
location @bialet {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://bialet;
}
```
Caddy:
```
example.com {
reverse_proxy 127.0.0.1:7001 127.0.0.1:7002 127.0.0.1:7003
}
```
This is worker scaling on one machine, not a cluster. The workers share one
SQLite file, so the constraints of a single database still apply:
- **One writer at a time.** SQLite serializes writes. A worker waits up to
5 seconds for the lock (`sqlite3_busy_timeout`) and then returns an error.
Enable WAL mode (`-w`) so readers do not block on a writer, and keep the app
and database on a local disk — not NFS or another network filesystem.
- **Sessions are shared.** They live in the `BIALET_SESSION` table, so any
worker can serve any request. Sticky sessions are not required.
- **Migrations run in every process at startup.** Keep `_migration.wren`
idempotent (`CREATE TABLE IF NOT EXISTS`, ...), and start the workers one at
a time on the first deploy so two of them do not run the same migration
concurrently.
- **Resource limits are per worker.** `-m` and `-c` apply to each process, so
three workers get three times the memory and CPU budget. Size them against
the host, not the app.
- **Each worker needs its own port.** `-p` is per process; the supervisor and
HTTP child for one worker are independent of the others.
> **Pitfall: cron runs once per worker.**
> `_cron.wren` is evaluated once a minute by every process, so four workers
> fire every job four times. Make jobs idempotent, or gate them with a
> database flag so only one worker does the work. There is no `--no-cron`
> flag yet.
Scaling across machines is a different problem: it needs a shared database
server, which Bialet does not support. That is the point at which a different
stack fits better.
## No Restart Needed on Deploy
When you push new code to your server, the Bialet server **does not need to
be restarted**. It watches `.wren` files for changes and picks them up
automatically.
### Auto-Migration
If your app has a `_migration.wren` file (or `/_app/migration.wren`), any
pending database migrations run automatically **each time the migration file
is created or modified**. Just deploy the new file and Bialet runs the
migrations before serving the next request. No manual steps, no downtime.
This means your deploy flow is:
```bash
scp -r ./src/* user@your-server:/www/your-app/
# Done. Migrations run, code reloads, server keeps running.
```
## Static Files
Bialet serves static files (CSS, JS, images, fonts) directly. For better
performance, configure your reverse proxy to:
- **Cache** static assets (add `Cache-Control` headers)
- **Gzip** or **brotli** compress text-based assets (CSS, JS, HTML, SVG)
It's also safe to serve static files from the proxy directly instead of
proxying to Bialet — just add a `location` block pointing to your app
directory.
## Reverse Proxy Setups
### nginx
```nginx
server {
listen 80;
listen [::]:80;
server_name example.com;
# Serve static files directly from disk (optional, faster)
root /www/example.com;
location / {
# Try static file first, fall back to Bialet
try_files $uri @bialet;
}
# Gzip static assets
location ~* \.(css|js|svg|woff2|png|jpg|jpeg|gif|ico|html)$ {
expires 7d;
add_header Cache-Control "public, immutable";
try_files $uri =404;
}
location @bialet {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:7001;
}
}
```
For Let's Encrypt TLS, wrap with:
```nginx
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# ... same location blocks as above ...
}
server {
listen 80;
listen [::]:80;
server_name example.com;
return 301 https://$host$request_uri;
}
```
### Apache
Enable the required modules:
```bash
sudo a2enmod proxy proxy_http rewrite headers expires
```
Virtual host configuration:
```apache
ServerName example.com
# Gzip
AddOutputFilterByType DEFLATE text/html text/css text/javascript
AddOutputFilterByType DEFLATE application/javascript application/json
AddOutputFilterByType DEFLATE image/svg+xml
# Cache static assets
ExpiresActive On
ExpiresByType text/css "access plus 7 days"
ExpiresByType text/javascript "access plus 7 days"
ExpiresByType image/png "access plus 7 days"
ExpiresByType image/jpeg "access plus 7 days"
ExpiresByType image/svg+xml "access plus 7 days"
ExpiresByType font/woff2 "access plus 30 days"
# Serve static files directly
DocumentRoot /www/example.com
RewriteEngine On
# If the file exists, serve it
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f
RewriteRule ^ - [L]
# Otherwise proxy to Bialet
RewriteRule ^/(.*)$ http://127.0.0.1:7001/$1 [P,L]
ProxyPreserveHost On
ProxyPassReverse / http://127.0.0.1:7001/
```
### Caddy
Caddy is the simplest option — it handles TLS automatically:
```
example.com {
encode gzip zstd
@static {
file
path *.css *.js *.svg *.woff2 *.png *.jpg *.jpeg *.gif *.ico *.html
}
header @static Cache-Control "public, max-age=604800, immutable"
reverse_proxy 127.0.0.1:7001
}
```
That's it. Caddy obtains and renews certificates automatically.
## Hardening the Proxy
The proxy is your first line of defense. A Bialet worker handles one request
at a time, so a slow or hostile client delays every request behind it.
Bialet's own header and body deadlines bound how long that can last, but the
proxy should still cap body size, enforce a shorter read deadline, and buffer
requests before they reach the worker.
Key directives, regardless of which proxy you run:
- **Cap the request body.** Bialet rejects request bodies larger than the
`-b` limit (default 128 KB) with `413 Payload Too Large` *before* parsing
them, so a body can never stall the Wren runtime. The effective cap is the
smaller of `-b` and a memory-safe ceiling (`-m` / 512) so a body can never
push the fork()ed child past its `RLIMIT_AS` budget — at the default 128 MB
soft limit that ceiling is 256 KB, so the default `-b 128` is fully
effective. Set the proxy's body limit to the smallest your
app needs — 1 MB is a sane default for the proxy.
- **Set a body-read deadline.** Bialet already bounds this itself: 5 seconds
for the whole header block and 30 seconds for the body, with each `recv()`
capped at 5 seconds, after which the connection is dropped. A proxy-side
timeout still helps because it rejects a stalled client before it reaches
the worker: `client_body_timeout` in nginx, `RequestReadTimeout ... MinRate`
in Apache.
- **Buffer the body at the proxy.** Read the full request before forwarding
it, so the upstream socket is never held open by a slow client.
- **Bind Bialet to `127.0.0.1`** and only expose the proxy to the internet.
- **Deny private files at the proxy too.** Bialet already returns 403 for
`_`/`.`-prefixed files, but blocking them at the proxy adds a second layer
in case an application or symlink ever serves one (see [Security](security.md)).
### nginx
```nginx
server {
listen 80;
listen [::]:80;
server_name example.com;
# Cap body size and enforce a total read deadline.
client_max_body_size 1m;
client_body_timeout 10s;
# Deny private files at the proxy (defense in depth).
location ~ (^|/)[_.] {
return 403;
}
# Serve static files directly from disk (optional, faster)
root /www/example.com;
location / {
# Try static file first, fall back to Bialet
try_files $uri @bialet;
}
# Gzip static assets
location ~* \.(css|js|svg|woff2|png|jpg|jpeg|gif|ico|html)$ {
expires 7d;
add_header Cache-Control "public, immutable";
try_files $uri =404;
}
location @bialet {
proxy_request_buffering on;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:7001;
}
}
```
Note: the `location ~ (^|/)[_.]` block matches any path segment that starts
with `_` or `.`, which covers `_db.sqlite3` and dotfiles such as `.env`. If
your app legitimately serves files with such names, drop this block — but
prefer renaming those files.
### Apache
```apache
ServerName example.com
# Cap body size (bytes) and set a total read timeout (needs mod_reqtimeout).
LimitRequestBody 1048576
RequestReadTimeout header=20-40,MinRate=500 body=30,MinRate=500
# Gzip
AddOutputFilterByType DEFLATE text/html text/css text/javascript
AddOutputFilterByType DEFLATE application/javascript application/json
AddOutputFilterByType DEFLATE image/svg+xml
# Cache static assets
ExpiresActive On
ExpiresByType text/css "access plus 7 days"
ExpiresByType text/javascript "access plus 7 days"
ExpiresByType image/png "access plus 7 days"
ExpiresByType image/jpeg "access plus 7 days"
ExpiresByType image/svg+xml "access plus 7 days"
ExpiresByType font/woff2 "access plus 30 days"
# Deny private files at the proxy (defense in depth).
RewriteRule ^(.*)(^|/)[_.][^/]*$ - [F,L]
# Serve static files directly
DocumentRoot /www/example.com
RewriteEngine On
# If the file exists, serve it
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f
RewriteRule ^ - [L]
# Otherwise proxy to Bialet
RewriteRule ^/(.*)$ http://127.0.0.1:7001/$1 [P,L]
ProxyPreserveHost On
ProxyPassReverse / http://127.0.0.1:7001/
```
`RequestReadTimeout` is provided by `mod_reqtimeout`, enabled with
`a2enmod reqtimeout`. The `MinRate` clause stops a slow-drip client that would
otherwise never trip the absolute timeout.
### Caddy
Caddy does not have a per-location body-size directive, but you can cap
request bodies with a request matcher:
```
example.com {
encode gzip zstd
@static {
file
path *.css *.js *.svg *.woff2 *.png *.jpg *.jpeg *.gif *.ico *.html
}
header @static Cache-Control "public, max-age=604800, immutable"
@private {
path_regexp private (^|/)[_.]
}
respond @private 403
reverse_proxy 127.0.0.1:7001 {
flush_interval -1
}
}
```
Caddy reads request bodies before proxying by default. For a total body
deadline, front Caddy with a timeout-capable proxy or enforce it at the app
level.
## Cloudflare Tunnel (Alternative)
If you do not control a server or a domain, [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
exposes a local Bialet server over a public HTTPS URL **without opening a
port, configuring a proxy, or buying DNS**. `cloudflared` keeps an outbound
connection to Cloudflare's edge; requests arrive at your machine through that
tunnel. Cloudflare terminates TLS and buffers slow clients, which covers most
of what a reverse proxy does.
Install `cloudflared` ([official packages](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)):
```bash
sudo apt-get install -y cloudflared
```
Start Bialet bound to localhost, then point a quick tunnel at it:
```bash
bialet -p 7001 /www/myapp
cloudflared tunnel --url http://127.0.0.1:7001
```
`cloudflared` prints a `https://.trycloudflare.com` URL. Open it and
your app is live. No account, no configuration.
> **Pitfall: the URL is temporary.** A quick tunnel dies when `cloudflared`
> stops, and the next run gets a **new** random hostname. Fine for demos and
> previews; useless as a stable endpoint.
For a stable hostname you need a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/),
which requires a Cloudflare account and a domain on their DNS:
```bash
cloudflared tunnel login
cloudflared tunnel create myapp
cloudflared tunnel route dns myapp app.example.com
cloudflared tunnel run --url http://127.0.0.1:7001 myapp
```
A named tunnel persists across restarts and can run as a systemd unit with
`cloudflared service install`.
Security notes that still apply:
- **Bind Bialet to `127.0.0.1`.** The tunnel forwards to localhost; do not
add `-h 0.0.0.0`. Only Cloudflare's edge ever talks to your server.
- **Cap the request body.** Cloudflare does not enforce a body-size limit for
you. Keep Bialet's `-b` default (128 KB) or lower it.
- **Private files are still private.** Bialet returns 403 for `_`/`.`
prefixed files; a tunnel does not change that.
## Running Bialet as a Service
### systemd (Ubuntu / Debian)
Create a unit file to keep Bialet running and auto-start on boot.
First, create a group service (optional — useful if you run multiple apps):
**`/etc/systemd/system/bialet.service`**
```ini
[Unit]
Description=Bialet group
[Service]
Type=oneshot
ExecStart=/bin/true
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
```
Then create one unit per app:
**`/etc/systemd/system/example.com.service`**
```ini
[Unit]
Description=example.com in Bialet
PartOf=bialet.service
After=bialet.service
[Service]
User=root
WorkingDirectory=/www/example.com
ExecStart=bialet -p 7001 -m 1024 -M 2048 -l /var/log/bialet/example.com.log -d /www/example.com.sqlite /www/example.com
Restart=on-failure
[Install]
WantedBy=bialet.service
```
Enable and start:
```bash
sudo mkdir -p /var/log/bialet /www/example.com
sudo systemctl daemon-reload
sudo systemctl enable bialet.service example.com.service
sudo systemctl start bialet.service example.com.service
```
### Multiple Apps on One Server
Run each app on a different port and proxy by hostname:
```bash
bialet -p 7001 /www/site-a # proxied from site-a.com
bialet -p 7002 /www/site-b # proxied from site-b.com
```
Point each nginx `proxy_pass` / Apache `ProxyPass` / Caddy `reverse_proxy` to
the matching port.
## Docker
Run the published [`bialet/bialet`](https://hub.docker.com/r/bialet/bialet) image
directly with [Docker](https://docs.docker.com/):
```bash
docker run -t -p 7001:7001 -v "$PWD":/var/www bialet/bialet
```
The `-t` flag allocates a pseudo-TTY so the server's logs are colored. Drop it
if you want plain, uncolored output.
The image serves the current directory, which is mounted at `/var/www`.
### Customizing the Application Directory
To serve a different directory, mount it at `/var/www`:
```bash
docker run -t -p 7001:7001 -v /path/to/app:/var/www bialet/bialet
```
### Changing the Default Port
The application listens on port `7001` inside the container. To expose a
different host port, use `-p`:
```bash
docker run -t -p 8080:7001 -v "$PWD":/var/www bialet/bialet
```
(sqlite-wal-mode-production)=
## SQLite WAL Mode (Production)
Enable WAL with the `-w` flag:
```bash
bialet -w -p 7001 /www/myapp
```
### What Is WAL?
WAL (Write-Ahead Logging) is an alternative journal mode for SQLite.
Instead of writing changes directly to the main database file, SQLite
appends them to a separate `-wal` file first, then periodically merges
them back (a process called *checkpointing*).
### Why It Matters for a Web Server
By default, SQLite uses a *rollback journal*. In that mode, **readers block
writers and writers block readers**. On a web server handling concurrent
requests, this means:
- A page loading data (`SELECT`) blocks a form submission (`INSERT`)
- Two simultaneous form submissions queue up behind each other
- Under any real traffic, you get `SQLITE_BUSY` errors
WAL fixes this by decoupling reads from writes:
| | Rollback Journal (default) | WAL mode (`-w`) |
|---------------------|---------------------------|---------------------|
| Readers vs. writers | Block each other | Work concurrently |
| Multiple readers | OK | OK |
| Multiple writers | One at a time (queued) | One at a time (queued) |
| Write performance | Baseline | Often faster |
In practice, this means a user submitting a comment form won't stall another
user browsing the page, and your cron tasks (which may write to the DB) won't
interfere with normal traffic.
### Disk Footprint
WAL mode creates two extra files alongside your database:
- `_db.sqlite3-wal` — the write-ahead log (grows during writes)
- `_db.sqlite3-shm` — shared memory index (small, fixed size)
The WAL file shrinks automatically on checkpoint. For most apps, it stays
under a few megabytes.
### When You Can Skip It
WAL is not strictly necessary if:
- Your app is read-only or single-user
- Traffic is extremely low (a handful of requests per minute)
- You're prototyping locally
For anything serving real users, enable it with `-w`. The overhead is
negligible and the concurrency benefit is immediate.
## Server Resource Limits
Use CLI flags to constrain resources per app:
| Flag | Description | Default | Example |
|------|------------------------|---------|------------------|
| `-m` | Soft memory limit (MB) | 128 | `-m 1024` |
| `-M` | Hard memory limit (MB) | 256 | `-M 2048` |
| `-c` | Soft CPU limit (%) | 15 | `-c 25` |
| `-C` | Hard CPU limit (%) | 30 | `-C 50` |
| `-b` | Max request body (KB) | 128 | `-b 512` |
| `-u` | Max per-file upload | 4 MB | `-u 8MB` |
| `-w` | SQLite WAL mode | off | `-w` |
The request-body cap is the smaller of `-b` and the memory-safe ceiling
(`-m` / 512, about 256 KB at the default 128 MB soft limit). Bodies over the
cap are rejected with `413` before parsing; raising `-m` raises the ceiling.
Uploads are capped by `-u` and must also fit inside the body cap, so the
effective per-file limit is the smaller of the two minus ~8 KB of multipart
framing — about 120 KB at the defaults. Raise `-b` (and `-m` when the ceiling
binds) together with `-u` to allow large files. See
[File Size Limits](file.md). SQLite foreign keys (`-f`) and synchronous mode
(`-s`) are also startup flags; see [Upload and SQLite Tuning](usage.md).
Example for a production app:
```bash
bialet -p 7001 -m 1024 -M 2048 -c 25 -C 50 -w -b 1100 -u 1MB \
-l /var/log/bialet/app.log /www/myapp
```
Raises the default body cap so the app accepts uploads up to ~1 MB; drop
`-b`/`-u` if it does not handle uploads at all.
## Quick Deploy Checklist
1. **Copy the binary** — `scp bialet user@host:/usr/local/bin/`
2. **Copy your app** — `scp -r *.wren static/ user@host:/www/myapp/`
3. **Set up the reverse proxy** — nginx, Apache, or Caddy (see above),
including the body-size cap, read timeout, and private-file deny from the
hardening section
4. **Create the systemd unit** — so it starts on boot and restarts on crash
5. **Point your DNS** — A/AAAA record to your server's IP
6. **Add TLS** — Let's Encrypt via certbot (nginx/Apache) or Caddy's auto-TLS
# Reference
This document provides the API reference for Bialet's built-in classes and external modules.
## Core Classes
The following classes are available by default in all Bialet applications without requiring imports:
- **Request** - Handle incoming HTTP requests
- **Response** - Construct and manage HTTP responses
- **Cookie** - Manage cookies
- **Session** - Manage session data
- **Json** - Handle JSON data
- **Util** - Utility helper methods
- **Config** - Manage configuration settings
- **Db** - Database interactions
- **Http** - Perform HTTP requests
- **Date** - Date and time operations
- **File** - File operations
- **Markdown** - Render Markdown content to HTML
- **System** - Logging and output utilities
- **HtmlNode** - A string of already-safe HTML that `{{ }}` leaves unescaped
## HtmlNode
`HtmlNode` wraps a string of already-rendered HTML. HTML string literals
(`...
`), the result of a `{{ }}` block, and `String.raw` all produce
`HtmlNode` values. Interpolating an `HtmlNode` renders it verbatim, while
plain strings are auto-escaped.
### new(string)
Wraps a string as safe HTML. Only use this for markup you control or have
already escaped.
### toString
Returns the raw HTML string.
### +(other)
Concatenates the raw HTML with `other.toString`, returning a new `HtmlNode`.
### raw
Returns `this` — the node is already safe.
## External Classes
External classes must be imported explicitly using the GitHub shorthand or full URLs. See [External Modules](external-modules.md) for details on how to import, author, and manage external modules.
---
## Request
A class to handle incoming HTTP requests, parsing their content, and providing
convenient access to their components.
### init(message, route, files, fields)
Initializes a new Request object. Bialet calls this for you before your code
runs.
- `message`: The raw HTTP request message. For a `multipart/form-data` request
it holds the request line and headers only (see [body](#body)).
- `route`: The route the request is targeting.
- `files`: The uploaded files data.
- `fields`: The text fields of a `multipart/form-data` body, already extracted.
Empty for any other request.
### parseQuery(query)
Parses the query string of the request.
- `query`: The query string part of the URL.
### method
Returns the HTTP method of the request (uppercase, e.g., "GET", "POST", "PUT", "DELETE").
### uri
Returns the URI of the request.
### body
Returns the body content of the request.
For a `multipart/form-data` request the body is an empty string. The file
content never enters Wren, and the text fields are read with
[post(name)](#postname). Use `Request.post()` and `Request.file()` instead of
parsing the body.
### isPost
Checks if the request method is POST.
### isJson
Checks if the request's content type is JSON.
### json()
Parses and returns the JSON body of the request. This is a convenience method equivalent to `Json.parse(Request.body)`.
Example:
```wren
if (Request.isJson) {
var data = Request.json()
var name = data["name"]
var email = data["email"]
}
```
### header(name)
Returns the value of a specified request header.
- `name`: The name of the header.
### get(name)
Returns the value of a specified query parameter.
- `name`: The name of the query parameter.
### query(name)
Alias for `get(name)`. Returns the value of a specified query parameter.
- `name`: The name of the query parameter.
### post(name)
> ⚠️ **CRITICAL: Returns `Null` when the key is not present.**
> The return type is `String | Null`. You **MUST** handle `null`
> before calling any string method (`.toString`, `.count`, `.trim`,
> concatenation, interpolation). This is the #1 production crash cause.
> **NEVER assume the field exists. ALWAYS provide a default or null check.**
Returns the value of a specified POST parameter, or `null` if not found.
- `name`: The name of the POST parameter.
- **Returns**: `String` if the key exists in the POST body, `Null` otherwise.
Works for `application/x-www-form-urlencoded` and `multipart/form-data` forms.
For a multipart form it returns the text fields only: a file part is read with
[file(name)](#filename) and never appears here. Line breaks in a value (a
`