@orieljs/framework 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/database.md

@@ -0,0 +1,236 @@
+# Database: getting started
+
+Your app talks to SQLite, PostgreSQL or MySQL through one API: raw SQL with the `DB` facade, the query builder, and
+your models.
+
+## Introduction
+
+Oriel reaches your database through [Kysely](https://kysely.dev), with three drivers:
+
+- **SQLite**, with `better-sqlite3` on Node and Bun's own `bun:sqlite` on Bun. A new app uses it, so you need no
+  database server to start.
+- **PostgreSQL**, with `pg`.
+- **MySQL**, with `mysql2`.
+
+`pg` and `mysql2` aren't installed with the framework: install the one you need, `npm install pg` or
+`npm install mysql2`. A driver is loaded the first time your app queries the database.
+
+### Configuration
+
+Your connections are in `config/database.ts`. `default` names the one your app uses, `sqlite` unless
+`DB_CONNECTION` names another:
+
+```ts
+declare const basePath: string
+declare function join(...paths: string[]): string
+// ---cut---
+const database = {
+  default: env('DB_CONNECTION', 'sqlite'),
+  connections: {
+    sqlite: { driver: 'sqlite', database: env('DB_DATABASE', join(basePath, 'database/database.sqlite')) },
+    pgsql: { driver: 'pgsql', host: env('DB_HOST', '127.0.0.1'), port: Number(env('DB_PORT', 5432)), database: env('DB_DATABASE', 'oriel') },
+  },
+}
+```
+
+Each connection takes `host`, `port`, `database`, `username` and `password`, read from the `DB_*` variables of your
+`.env` (see [Databases and migrations](installation.md#databases-and-migrations)). `pool.max` is the size of the
+connection pool, 10 unless you set it. A `pgsql` connection takes a `search_path`, and a `mysql` one a `charset`,
+`utf8mb4` unless you set it.
+
+#### SQLite configuration
+
+A SQLite connection's `database` is the path of the database file. A new app's is `database/database.sqlite`, as an
+absolute path, since a relative one is opened from the folder your app runs in; `migrate` creates the file. `:memory:`
+gives a database in memory, which your tests use.
+
+SQLite checks foreign keys, as `foreign_key_constraints: true` asks; set it to `false` to turn the checks off. Changing
+a table on SQLite rebuilds it: [SQLite and schema changes](migrations.md#sqlite-and-schema-changes) explains.
+
+#### Configuration using URLs
+
+A `pgsql` or `mysql` connection can take a single `url`, such as the one a hosting provider gives you, in `DB_URL`:
+
+```dotenv
+DB_URL=postgresql://user:secret@db.example.com:5432/blog
+```
+
+A URL's parts win over the separate keys. A SQLite connection ignores `url`: give it a `database` path.
+
+> [!NOTE]
+> Laravel's read and write connections, its `sqlsrv` driver and a connection's table `prefix` aren't in Oriel. A new
+> app's `config/database.ts` keeps a `prefix: ''` line from Laravel's file, which nothing reads.
+
+## Running SQL queries
+
+The `DB` facade runs raw SQL on the default connection. Every method is async.
+
+#### Running a select query
+
+`DB.select()` runs a `select`, with the values for its `?` placeholders in an array, and returns the rows as objects:
+
+```ts title="app/Http/Controllers/UserController.ts"
+import { DB } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class UserController extends Controller {
+  /** Show a list of all of the application's users. */
+  async index() {
+    const users = await DB.select<{ id: number; name: string }>('select * from users where active = ?', [1])
+
+    return { users }
+  }
+}
+```
+
+The values are bound, never written into the SQL, so they are safe from SQL injection. The type you give the rows is
+a cast, not a check.
+
+> [!NOTE]
+> Laravel also takes named bindings (`:id`). Oriel takes `?` only, and finds them by splitting the SQL at each `?`,
+> so a `?` inside a string, or PostgreSQL's `?` operator, counts as one too: pass such text as a binding.
+
+#### Using multiple database connections
+
+`DB.connection()` returns another connection of `config/database.ts`, with `select()`, `statement()`,
+`affectingStatement()`, `table()` and `transaction()`:
+
+```ts
+const users = await DB.connection('sqlite').select('select * from users')
+```
+
+`DB.usingConnection('sqlite', () => ...)` runs a function with another connection as the default, and puts the default
+back after it.
+
+#### Using Kysely
+
+Oriel's queries run on Kysely. `DB.kysely()` returns the connection's Kysely instance, for a query the query builder
+doesn't write; inside a transaction it is the transaction's, so its queries join it:
+
+```ts
+const rows = await DB.kysely().selectFrom('users').select(['id', 'name']).where('votes', '>', 100).execute()
+```
+
+#### Running an insert statement
+
+```ts
+await DB.insert('insert into users (id, name) values (?, ?)', [1, 'Marc'])
+```
+
+#### Running an update statement
+
+`DB.update()` returns the number of rows it changed:
+
+```ts
+const affected = await DB.update('update users set votes = 100 where name = ?', ['Anita'])
+```
+
+#### Running a delete statement
+
+`DB.delete()` returns the number of rows it deleted:
+
+```ts
+const deleted = await DB.delete('delete from users')
+```
+
+#### Running a general statement
+
+`DB.statement()` runs SQL that returns nothing, such as a schema change, and `DB.affectingStatement()` returns the
+number of rows a statement changed:
+
+```ts
+await DB.statement('drop table users')
+```
+
+#### Raw expressions
+
+`DB.raw()` makes an expression the query builder writes as it is, with its own bindings:
+
+```ts
+const users = await DB.table('users').select(DB.raw('count(*) as user_count, status')).groupBy('status').get()
+```
+
+A raw expression is SQL you write, so never put a user's input in it: bind it with `?` instead.
+
+### Values in bindings
+
+Oriel turns some values into what the database stores: `true` and `false` become `1` and `0` (except on PostgreSQL,
+which has booleans), a `Date` becomes its UTC time as `'2026-01-02 03:04:05'`, an object or an array becomes JSON,
+and `undefined` becomes `null`.
+
+Dates come back as strings, on every driver: your models' date casts turn them into `Date` objects.
+
+## Database transactions
+
+`DB.transaction()` runs a function in a transaction. When the function throws, the transaction is rolled back and the
+error is thrown again; otherwise it is committed:
+
+```ts
+await DB.transaction(async () => {
+  await DB.update('update users set votes = 1')
+
+  await DB.delete('delete from posts')
+})
+```
+
+The queries your function runs, through the facade, the query builder or your models, are in the transaction, and
+those of other requests running at the same time aren't. A transaction inside another uses a savepoint, so an inner
+one that throws rolls back only its own work. The function's result is `transaction()`'s:
+
+```ts
+const user = await DB.transaction(async () => {
+  const id = await DB.table('users').insertGetId({ name: 'Taylor', email: 'taylor@example.com', password: '' })
+
+  return DB.table('users').where('id', id).first()
+})
+```
+
+> [!NOTE]
+> Laravel's `transaction()` takes a number of attempts for deadlocks as its second argument. Oriel's doesn't: catch
+> the error and run it again yourself.
+
+### Manually using transactions
+
+`DB.beginTransaction()` starts a transaction that lasts, for every query on the connection, until `DB.commit()` or
+`DB.rollBack()`:
+
+```ts
+await DB.beginTransaction()
+
+try {
+  await DB.update('update users set votes = 1')
+  await DB.commit()
+} catch (error) {
+  await DB.rollBack()
+  throw error
+}
+```
+
+Prefer `transaction()`: a manual transaction takes in the queries of every request until it ends, which suits a
+script or a test, not a request.
+
+## Logging queries
+
+`DB.enableQueryLog()` records each query the default connection runs, with its bindings and how many milliseconds it
+took, and `DB.getQueryLog()` returns them:
+
+```ts
+DB.enableQueryLog()
+
+await DB.table('users').get()
+
+const queries = DB.getQueryLog() // [{ query: 'select * from "users"', bindings: [], time: 0.4 }]
+```
+
+A query that fails throws a `QueryError`, whose message ends with the connection's name and the SQL, and which has
+`sql` and `bindings` fields.
+
+> [!NOTE]
+> Laravel's `DB::listen()` and its cumulative query time warnings, the `db` command and the `db:show` and `db:table`
+> commands aren't in Oriel.
+
+## Closing connections
+
+Your app's server, its `oriel` commands and its queue workers close their database connections when they shut down. A
+script of your own can end with `await app.shutdown()`, or close them with `await DB.disconnectAll()`;
+`DB.disconnect('mysql')` closes one.

package/docs/deployment.md

@@ -0,0 +1,371 @@
+# Deployment
+
+To run your app in production, build its assets, set its environment, and keep its server, queue workers and
+scheduler running under a process manager.
+
+## Introduction
+
+An Oriel app is a long-running process: one server answers every request, where a PHP app starts afresh for each one.
+So deploying it means starting that process, keeping it running, and restarting it with each new version, along with
+the processes beside it: the queue workers, the scheduler and, for the Inertia kits with server-side rendering, the
+SSR server.
+
+An app whose pages are the same for every visitor can skip the server altogether: [Static export](export.md) saves its
+pages as files any static host serves. On Vercel, your app runs without a server of its own, in a function that starts
+when requests come: see [Deploying to Vercel](#deploying-to-vercel).
+
+## Server requirements
+
+Your server needs **Node 22** or later, or **Bun 1.2** or later. On Node, your app's TypeScript runs through `tsx`,
+which every app has as a dependency; Bun runs it as it is. There is no compile step for your server code.
+
+A PostgreSQL or MySQL database needs its driver in your dependencies, `pg` or `mysql2`. SQLite needs nothing more.
+
+## Building your application
+
+On each deploy, install the dependencies from your lockfile, build the assets, and run the migrations:
+
+```sh
+npm ci
+npm run build
+node oriel migrate --force
+```
+
+`npm run build` writes your pages' scripts and styles into `public/build`, and, in the Inertia kits with server-side
+rendering, the SSR bundle into `bootstrap/ssr`. The API kit has no `build` script: skip that step. `migrate` asks
+for `--force` in production, since it changes your database.
+
+Leave `public/hot` off your server: Vite writes it while `npm run dev` runs, and while it exists, your pages load their
+assets from a Vite dev server rather than from `public/build`. Git ignores it, so a deploy from your repository
+doesn't have it.
+
+## Configuring the environment
+
+Give your server its own values, in its environment or in its own `.env` (see [Configuration](configuration.md)). At
+least:
+
+```dotenv
+APP_ENV=production
+APP_DEBUG=false
+APP_KEY=base64:...
+APP_URL=https://example.com
+```
+
+`APP_KEY` must be the same on every server of the app, and stay the same from one deploy to the next: it decrypts
+your cookies and sessions, and checks your signed URLs. Generate it once, with `node oriel key:generate --show`.
+
+In production, `migrate` and the other commands that change your data need `--force`, `key:generate` won't replace a
+key that is set, `migrate` doesn't rewrite `types/models.d.ts`, and the kits' dashboard hides its Getting started
+checklist.
+
+## Server configuration
+
+### Running the server
+
+`public/index.ts` is your app's production entry point. It creates your app and serves it:
+
+```sh
+node --import tsx public/index.ts
+```
+
+On Bun, run `bun public/index.ts`. The server listens on `127.0.0.1`, on the port the `PORT` variable names, or
+`SERVER_PORT`, or 8000. It serves with `node:http` on Node and `Bun.serve()` on Bun.
+
+`node oriel serve` runs the same server through your app's command line, and takes `--host` and `--port`; `npm start`
+runs it too, and so does the CI workflow the installer writes. Leave `--watch` out in production: it restarts the
+server on every file change.
+
+### Containers
+
+In a container, the server must listen on every interface, not only on `127.0.0.1`, or nothing outside the container
+reaches it. With `node oriel serve`, pass `--host=0.0.0.0`:
+
+```sh
+node oriel serve --host=0.0.0.0 --port=8000
+```
+
+With `public/index.ts`, give `serve()` the host:
+
+```ts title="public/index.ts"
+// @filename: bootstrap/app.ts
+import type { Application } from '@orieljs/framework'
+export declare function createApplication(): Promise<Application>
+// ---cut---
+import { serve } from '@orieljs/framework'
+import { createApplication } from '../bootstrap/app'
+
+// Production entry: `node --import tsx public/index.ts`, or `bun public/index.ts`.
+await serve(await createApplication(), { hostname: '0.0.0.0' })
+```
+
+`serve()` takes these options:
+
+| Option | What it does |
+| --- | --- |
+| `hostname` | The address to listen on (default: `127.0.0.1`) |
+| `port` | The port (default: `PORT`, then `SERVER_PORT`, then 8000; 0 picks a free one) |
+| `publicPath` | The folder whose files are sent as they are (default: `public`); `false` turns it off |
+| `shutdownTimeout` | How long a shutdown waits for the requests in flight, in milliseconds (default: 10000) |
+| `signals` | Whether SIGINT and SIGTERM shut the server down (default: `true`) |
+
+Point your container's health check at the [health route](#the-health-route), `/up`.
+
+### Static files
+
+The server sends a file that exists in `public` before your routes run, so `public/build` and your icons need no
+other web server. The built assets, under `/build/assets/`, are sent with a year-long, immutable cache header, as
+their names change with their content. TypeScript files and dotfiles in `public` are never sent.
+
+A web server or a CDN in front of your app can serve `public` itself; then pass `publicPath: false` to `serve()`.
+
+### Behind a proxy
+
+Behind a load balancer or a proxy that ends TLS, your app sees the proxy's request: plain HTTP, from the proxy's
+address. List your proxies in `http.trusted_proxies`, in `config/http.ts`, so that `request().ip()`, `url()` and
+`route()` use the client's address, scheme and host from the `X-Forwarded-*` headers.
+[Configuring trusted proxies](requests.md#configuring-trusted-proxies) shows the settings.
+
+### Directory permissions
+
+Your app writes into `storage`: its logs, uploaded files, and the file cache and sessions when you use those drivers.
+The user that runs it needs write access there, and in `database` when you use SQLite.
+
+### Shutting down
+
+On SIGTERM or SIGINT, the server stops taking new connections and lets the requests in flight finish, for up to 10
+seconds (`shutdownTimeout`). Then the app shuts down: it closes the database pools and the Redis connections that the
+cache, the queue and the session opened, and writes out its logs. Then the process exits with code 0. A process
+manager that sends SIGTERM to stop or restart your app gets a clean exit, with no log line lost and no request cut
+short, unless it takes longer than 10 seconds. When closing the handles takes more than 10 seconds, the rest are given
+up on, so the process always exits.
+
+The `oriel` commands shut down the same way when they finish, and a queue worker finishes its current job first.
+
+## Optimization
+
+> [!NOTE]
+> Laravel caches its configuration, routes, events and views before it serves (`optimize`, `config:cache`,
+> `route:cache`, `event:cache`, `view:cache`), since each PHP request would read them again. Oriel's process reads
+> them once, when it starts, and keeps them: there is nothing to cache, and none of those commands exists.
+
+## Queue workers
+
+A queue worker is a process of its own: `node oriel queue:work` takes jobs off the queue until it is stopped (see
+[Running the queue worker](queues.md#running-the-queue-worker)). Keep your workers running with a process manager,
+such as Supervisor or systemd, which starts a new worker whenever one exits.
+
+A worker stops by itself in a few cases, so that the process manager starts it again with a clean slate:
+
+- `--memory`: when its JavaScript heap passes this many megabytes, 512 unless you set it (exit code 12).
+- `--max-jobs` and `--max-time`: after that many jobs, or seconds (exit code 0).
+- A job that runs past its timeout (exit code 1).
+- `queue:restart` (exit code 0, after the current job).
+
+Since a worker also exits with code 0, the process manager must restart it on every exit, not only on a failure. A
+Supervisor program for two workers:
+
+```ini
+[program:blog-worker]
+process_name=%(program_name)s_%(process_num)02d
+command=node oriel queue:work --sleep=3 --tries=3 --memory=512 --max-time=3600
+directory=/var/www/blog
+autostart=true
+autorestart=true
+stopasgroup=true
+killasgroup=true
+user=www-data
+numprocs=2
+redirect_stderr=true
+stdout_logfile=/var/www/blog/storage/logs/worker.log
+stopwaitsecs=3600
+```
+
+`stopwaitsecs` gives a worker time to finish its current job when Supervisor stops it: set it longer than your
+longest job.
+
+### Restarting the workers
+
+A worker loads your code once, so after a deploy it still runs the old code. Tell every worker to stop after its
+current job:
+
+```sh
+node oriel queue:restart
+```
+
+The process manager then starts each one again, on the new code. `queue:restart` leaves its signal in your app's
+default cache store, which the workers read after each job, so the workers and the command must share that store:
+the `database` store of a new app does, as long as they share the database. With the `array` store, a worker never
+sees the signal. While the cache can't be read, a worker goes on working.
+
+## Task scheduling
+
+The scheduler runs the tasks you schedule in `routes/console.ts`. Run `schedule:run` every minute with cron, and it
+runs the tasks that are due:
+
+```sh
+* * * * * cd /var/www/blog && node oriel schedule:run >> /dev/null 2>&1
+```
+
+Where you have no cron, as in many containers, run `node oriel schedule:work` under your process manager instead: it
+runs the due tasks every minute until it is stopped.
+
+## The SSR server
+
+The React, Vue, Svelte and Solid kits render their pages on the server through a separate SSR server. Keep it running
+beside your app, under your process manager:
+
+```sh
+node oriel inertia:start-ssr
+```
+
+On Bun, add `--runtime=bun`. It runs the bundle that `npm run build` wrote into `bootstrap/ssr`, on the port of
+`INERTIA_SSR_URL` (`http://127.0.0.1:13714` unless you set it), and exits when the bundle does. When no SSR server
+answers, your pages are rendered in the browser instead, so a restart doesn't break them.
+
+After a deploy, stop it, and let the process manager start it on the new bundle:
+
+```sh
+node oriel inertia:stop-ssr
+```
+
+The Angular kit, the Live kit and the API kit have no SSR server.
+
+## Reloading services
+
+After a deploy, every long-running process must restart to run the new code: your server, your queue workers and
+your SSR server. Restart the server through your process manager, then:
+
+```sh
+node oriel queue:restart
+node oriel inertia:stop-ssr
+```
+
+Laravel's `reload` command, which does both, isn't in Oriel.
+
+## Deploying to Vercel
+
+On Vercel there is no server to keep running: Vercel's CDN sends the files in `public`, and every other request goes
+to a function that runs your app. `node oriel vercel:build` writes both into `.vercel/output`, the folder Vercel
+deploys (its [Build Output API](https://vercel.com/docs/build-output-api)): `static` holds `public`, whose built
+assets are cached for a year as `serve()` sends them, and the function holds your app's code,
+`public/build/manifest.json` and your production dependencies. Your `.env` files and your
+SQLite databases are left out: the secrets come from Vercel's environment variables, and the database from a server.
+
+### Setting up the project
+
+Add a `vercel.json` to your app, so that Vercel's build runs the command:
+
+```json title="vercel.json"
+{
+  "framework": null,
+  "buildCommand": "npm run build && node oriel migrate --force && node oriel vercel:build"
+}
+```
+
+The API kit has no `build` script: leave `npm run build &&` out. Then import your repository in Vercel, or deploy from
+your machine with `npx vercel deploy`: either way, the build runs on Vercel's machines, which run Linux, as its
+functions do. The function holds native packages built for the machine that ran the build, such as esbuild, which
+`tsx` needs, so a function built on macOS or Windows fails on Vercel. `vercel:build` warns when it runs elsewhere than
+Linux: don't deploy that build with `vercel deploy --prebuilt`.
+
+`migrate --force` runs on every deploy, the previews' too. Give the Preview environment a database of its own, such as
+a branch of your production database, so that a preview never migrates your live data.
+
+### Environment variables
+
+Set your app's values in the project's settings, under Environment Variables:
+
+```dotenv
+APP_ENV=production
+APP_DEBUG=false
+APP_KEY=base64:...
+APP_URL=https://example.vercel.app
+DB_CONNECTION=pgsql
+DB_URL=postgres://...
+SESSION_DRIVER=database
+CACHE_STORE=database
+QUEUE_CONNECTION=sync
+INERTIA_SSR_ENABLED=false
+```
+
+Vercel gives them to the build, which runs the migrations, and to the function. PostgreSQL needs `pg` in your
+dependencies (`npm install pg`); Vercel's Marketplace has PostgreSQL databases with a free plan, which set `DB_URL`'s
+value for you under a name of their own, such as `DATABASE_URL`: copy it into `DB_URL`. When the address says
+`sslmode=require`, as Neon's do, `pg` warns on every cold start: write `sslmode=verify-full`, which also checks the
+server's certificate.
+
+### What changes on Vercel
+
+Vercel starts an instance of the function when requests come, and stops it when they stop. The first request to a new
+instance boots your app; the next ones reuse it. Nothing your app keeps in memory or on disk outlasts the instance,
+and each instance has its own, so:
+
+- **Your database is a server**, PostgreSQL or MySQL. The function's files are read-only, so SQLite can't write.
+- **Sessions and the cache** need a store every instance shares: `database` (the kits have the `sessions` and `cache`
+  tables' migrations) or `redis`. Sessions can also use `cookie`. `file` and `array` don't outlast the instance.
+- **Logs** go to stderr, which Vercel's logs show: the function sets `LOG_CHANNEL=stderr` when you don't set it.
+- **Vercel's proxy is trusted.** Every request reaches the function through it, and it sets the `X-Forwarded-*`
+  headers itself, so the function trusts them when `trusted_proxies`, in `config/http.ts`, is empty: your URLs keep
+  the browser's `https`, and `request().ip()` is the visitor's (see
+  [Configuring trusted proxies](requests.md#configuring-trusted-proxies)).
+- **Files your app stores** go on an `s3` disk (see [File storage](storage.md)): the `local` and `public` disks write
+  into `storage`, which the function can't.
+- **No queue worker or scheduler runs.** With `QUEUE_CONNECTION=sync`, a job runs during the request that dispatches
+  it.
+- **Inertia pages render in the browser**, as they do when no SSR server answers: the SSR server doesn't run on
+  Vercel. `INERTIA_SSR_ENABLED=false` skips asking it.
+
+### Caching pages on the CDN
+
+Pages that are the same for every visitor can be kept by Vercel's CDN, so that most requests for them never reach the
+function. The `cache.headers` middleware sets their `Cache-Control`: `s_maxage` is how many seconds the CDN keeps a
+page, and `stale_while_revalidate` how long it may still send the old copy while it fetches a new one:
+
+```ts title="routes/web.ts"
+import { Route, StartSession, VerifyCsrfToken, view } from '@orieljs/framework'
+
+Route.get('/pricing', () => view('pricing'))
+  .middleware('cache.headers:public;s_maxage=3600;stale_while_revalidate=60')
+  .withoutMiddleware(StartSession, VerifyCsrfToken)
+```
+
+`cache.headers` leaves a response that sets a cookie alone, so that the CDN never hands one visitor's cookies to the
+next. The `web` group's `StartSession` and `VerifyCsrfToken` set cookies on every page: take them off the pages you
+cache, as above. Those pages have no session, so they can't show who is signed in.
+
+## Debug mode
+
+`debug` in `config/app.ts` reads `APP_DEBUG`, and decides how much an error response shows (see
+[Error handling](errors.md#configuration)).
+
+> [!WARNING]
+> In production, `APP_DEBUG` must be `false`. The debug page shows your source code and your error messages, which
+> can hold secrets, to anyone who triggers an error.
+
+## The health route
+
+A new app answers `/up` with a small page and a 200 when it is running, for your uptime monitor, your load
+balancer or your container's health check. The route is outside the `web` middleware group, so it starts no session.
+`health` in `withRouting()`, in `bootstrap/app.ts`, sets its URI:
+
+```ts
+Application.configure({ basePath: '.' }).withRouting({ web: 'routes/web.ts', console: 'routes/console.ts', health: '/status' })
+```
+
+Each request to it dispatches the `DiagnosingHealth` event. A listener can check what your app needs, such as its
+database, and throw when it fails:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { DB, DiagnosingHealth, Event, ServiceProvider } from '@orieljs/framework'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Event.listen(DiagnosingHealth, async () => {
+      await DB.select('select 1')
+    })
+  }
+}
+```
+
+When a listener throws, the route answers 500, "Application experiencing problems", and the error is reported. With
+`APP_DEBUG=true`, the error page shows the error instead.