@orieljs/framework 0.1.0-alpha.6 → 0.1.0-alpha.7

package/docs/controllers.md

@@ -0,0 +1,406 @@
+# Controllers
+
+A controller groups the actions that handle related requests in one class: a `UserController` can show, store and
+update your users.
+
+## Writing controllers
+
+### Basic controllers
+
+`make:controller` writes a new controller in `app/Http/Controllers`:
+
+```sh
+node oriel make:controller UserController
+```
+
+A controller has any number of methods, each of which can answer a route. This one shows a user's profile:
+
+```ts title="app/Http/Controllers/UserController.ts"
+import { view } from '@orieljs/framework'
+import { User } from '../../Models/User'
+import { Controller } from './Controller'
+
+export class UserController extends Controller {
+  async show(id: string) {
+    return view('user.profile', { user: await User.findOrFail(id) })
+  }
+}
+```
+
+Point a route at a method by naming the controller and the method together. TypeScript checks that the method
+exists:
+
+```ts
+Route.get('/user/{id}', [UserController, 'show'])
+```
+
+When a request matches the route, a new `UserController` is made and its `show()` called with the route's
+parameters, in the order they appear in the URI. What the method returns becomes the response, as a closure's does.
+
+Every controller `make:controller` writes extends `Controller` from `app/Http/Controllers/Controller.ts`, which a new
+app has:
+
+```ts title="app/Http/Controllers/Controller.ts"
+import { Controller as BaseController } from '@orieljs/framework'
+
+/** The base controller every generated controller extends: `await this.authorize('update', post)` comes from it. */
+export abstract class Controller extends BaseController {}
+```
+
+The framework's `Controller` gives your controllers `authorize()` (see [authorizing actions](#authorizing-actions)). A
+controller doesn't have to extend it, but methods all your controllers share can go in your base class.
+
+### Single action controllers
+
+A controller for one complex action can be a class of its own, with a single `__invoke()` method:
+
+```ts title="app/Http/Controllers/ProvisionServerController.ts"
+import { Controller } from './Controller'
+
+export class ProvisionServerController extends Controller {
+  async __invoke() {
+    // ...
+  }
+}
+```
+
+Its route names only the class:
+
+```ts
+declare class ProvisionServerController {
+  __invoke(): Promise<void>
+}
+// ---cut---
+Route.post('/server', ProvisionServerController)
+```
+
+`--invokable` (or `-i`) writes one:
+
+```sh
+node oriel make:controller ProvisionServer --invokable
+```
+
+`make:controller` adds the `Controller` suffix to a name that lacks it, so this writes
+`ProvisionServerController.ts` in `app/Http/Controllers`.
+
+## Controller middleware
+
+Give a controller's routes their middleware in your route files, on the route or on a group:
+
+```ts
+Route.get('/profile', [UserController, 'show']).middleware('auth')
+```
+
+> [!NOTE]
+> Laravel's controllers can also list their own middleware, with a static `middleware()` method. Oriel's can't: the
+> router reads every route's middleware from the route files, so they stay in one place.
+
+## Resource controllers
+
+A resource is something your users create, read, update and delete, such as a photo. `--resource` (or `-r`) writes a
+controller with a method for each of those actions:
+
+```sh
+node oriel make:controller PhotoController --resource
+```
+
+```ts title="app/Http/Controllers/PhotoController.ts"
+import { Controller } from './Controller'
+
+export class PhotoController extends Controller {
+  async index() {
+    //
+  }
+
+  async create() {
+    //
+  }
+
+  async store() {
+    //
+  }
+
+  async show(photo: unknown) {
+    //
+  }
+
+  async edit(photo: unknown) {
+    //
+  }
+
+  async update(photo: unknown) {
+    //
+  }
+
+  async destroy(photo: unknown) {
+    //
+  }
+}
+```
+
+`Route.resource()` then registers a route for each method:
+
+```ts
+declare class PhotoController {}
+// ---cut---
+Route.resource('photos', PhotoController)
+```
+
+`node oriel route:list` shows the routes it made.
+
+#### Actions handled by resource controllers
+
+| Verb | URI | Action | Route name |
+| --- | --- | --- | --- |
+| `GET` | `/photos` | `index` | `photos.index` |
+| `GET` | `/photos/create` | `create` | `photos.create` |
+| `POST` | `/photos` | `store` | `photos.store` |
+| `GET` | `/photos/{photo}` | `show` | `photos.show` |
+| `GET` | `/photos/{photo}/edit` | `edit` | `photos.edit` |
+| `PUT`, `PATCH` | `/photos/{photo}` | `update` | `photos.update` |
+| `DELETE` | `/photos/{photo}` | `destroy` | `photos.destroy` |
+
+Each `GET` route answers `HEAD` too. The parameter is the resource's name in the singular, so once your app has a
+`Photo` model, `{photo}` is [bound to it](routing.md#route-model-binding) and a missing photo is a 404.
+
+#### Specifying the resource model
+
+`--model` (or `-m`) types the methods with your model, and writes the resource controller even without `--resource`:
+
+```sh
+node oriel make:controller PhotoController --model=Photo
+```
+
+`show()`, `edit()`, `update()` and `destroy()` then take `photo: Photo`, and each method has a comment saying what it
+is for. When `app/Models` has no `Photo` yet, `make:model Photo` runs first.
+
+#### Generating form requests
+
+`--requests` (or `-R`), with `--model`, also writes a form request for `store()` and one for `update()`, and
+validates with them:
+
+```sh
+node oriel make:controller PhotoController --model=Photo --requests
+```
+
+This writes `app/Http/Requests/StorePhotoRequest.ts` and `app/Http/Requests/UpdatePhotoRequest.ts`, and `store()`
+starts with `const data = await StorePhotoRequest.validate()`. [Validation](validation.md) covers form requests.
+
+### Partial resource routes
+
+A resource route can register only some of its actions. List them in `only`, or the ones to leave out in `except`:
+
+```ts
+declare class PhotoController {}
+// ---cut---
+Route.resource('photos', PhotoController, { only: ['index', 'show'] })
+
+Route.resource('photos', PhotoController, { except: ['create', 'store', 'update', 'destroy'] })
+```
+
+> [!NOTE]
+> Laravel chains these settings onto the resource, as `->only([...])`. Oriel's `Route.resource()` registers its
+> routes as soon as you call it and returns nothing to chain onto, so it takes them in an options object, the third
+> argument: `only`, `except`, `names` and `parameters`.
+
+#### API resource routes
+
+An API has no pages with forms, so `Route.apiResource()` leaves out `create` and `edit`:
+
+```ts
+declare class PhotoController {}
+// ---cut---
+Route.apiResource('photos', PhotoController)
+```
+
+`--api` writes a controller without those two methods, and with `--model`, typed with the model:
+
+```sh
+node oriel make:controller PhotoController --api
+node oriel make:controller PhotoController --api --model=Photo
+```
+
+### Nested resources
+
+A resource that belongs to another, such as a photo's comments, is named with a dot:
+
+```ts
+declare class PhotoCommentController {}
+// ---cut---
+Route.resource('photos.comments', PhotoCommentController)
+```
+
+Its URIs hold both parameters, `/photos/{photo}/comments/{comment}`, and its routes are named `photos.comments.index`,
+`photos.comments.show` and so on. The actions receive the parameters in that order:
+
+```ts title="app/Http/Controllers/PhotoCommentController.ts"
+import { Controller } from './Controller'
+
+export class PhotoCommentController extends Controller {
+  async show(photo: string, comment: string) {
+    return { photo, comment }
+  }
+}
+```
+
+Each parameter is bound to its model by its name, on its own, once your app has `Photo` and `Comment` models.
+
+> [!NOTE]
+> Laravel's `scoped()` resources check that the comment belongs to the photo, and `shallow()` resources drop the
+> parent from the child's URIs. Oriel has neither: check the comment in the action, or find it through the photo's
+> relation.
+
+### Naming resource routes
+
+`names` replaces the names of some actions' routes:
+
+```ts
+declare class PhotoController {}
+// ---cut---
+Route.resource('photos', PhotoController, { names: { create: 'photos.build' } })
+```
+
+### Naming resource route parameters
+
+A resource's parameter is its name in the singular, with dashes turned into underscores: `blog-posts` gives
+`{blog_post}`. `parameters` names it yourself:
+
+```ts
+declare class AdminUserController {}
+// ---cut---
+Route.resource('users', AdminUserController, { parameters: { users: 'admin_user' } })
+```
+
+The `show` route's URI is then `/users/{admin_user}`.
+
+### Supplementing resource controllers
+
+Routes of your own can sit beside a resource's. Oriel matches a fixed segment before a parameter, so
+`/photos/popular` reaches `popular()` rather than `show()`, wherever you define it:
+
+```ts
+declare class PhotoController {
+  popular(): Promise<void>
+}
+// ---cut---
+Route.get('/photos/popular', [PhotoController, 'popular'])
+Route.resource('photos', PhotoController)
+```
+
+A resource can also sit in a group, which gives it a prefix, a name prefix or middleware:
+`Route.middleware('auth').resource('photos', PhotoController)`.
+
+## Dependency injection and controllers
+
+#### Constructor injection
+
+The [service container](container.md) makes a new controller for each request, with no constructor arguments. Take the
+services a controller needs with `inject()`, in a field:
+
+```ts title="app/Http/Controllers/PodcastController.ts"
+import { inject } from '@orieljs/framework'
+import { ConfigRepository } from '@orieljs/framework/contracts'
+import { Podcast } from '../../Models/Podcast'
+import { Controller } from './Controller'
+
+export class PodcastController extends Controller {
+  readonly #config = inject(ConfigRepository)
+
+  async index() {
+    return Podcast.latest().limit(this.#config.get('podcasts.per_page', 20)).get()
+  }
+}
+```
+
+> [!NOTE]
+> Laravel reads a controller's constructor type hints and injects what they name. TypeScript types are gone when your
+> app runs, so Oriel can't see them: it calls the constructor with no arguments, and `inject()` reads each service
+> from the container. A constructor with parameters receives `undefined` for them.
+
+#### Method injection
+
+An action receives the route's parameters and nothing else. Read the request with `request()`:
+
+```ts title="app/Http/Controllers/UserController.ts"
+import { redirect, request } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class UserController extends Controller {
+  async store() {
+    const name = request().string('name').toString()
+
+    // Store the user...
+
+    return redirect('/users')
+  }
+}
+```
+
+A route parameter still arrives as the method's argument:
+
+```ts
+Route.put('/user/{id}', [UserController, 'update'])
+```
+
+```ts title="app/Http/Controllers/UserController.ts"
+import { redirect, request } from '@orieljs/framework'
+import { User } from '../../Models/User'
+import { Controller } from './Controller'
+
+export class UserController extends Controller {
+  async update(id: string) {
+    const user = await User.findOrFail(id)
+
+    await user.update({ name: request().string('name').toString() })
+
+    return redirect('/users')
+  }
+}
+```
+
+> [!NOTE]
+> Laravel injects the request into an action that type-hints it, before the route parameters. TypeScript types are
+> gone when your app runs, so Oriel passes only the route parameters: they are always the action's arguments, in URI
+> order, and the request comes from `request()`.
+
+## Authorizing actions
+
+`this.authorize()` checks an ability for the signed-in user, through your gates and policies. When the user may not,
+it throws, and the request ends with a 403, or the status the policy chose:
+
+```ts title="app/Http/Controllers/PostController.ts"
+import { redirect, request } from '@orieljs/framework'
+import type { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class PostController extends Controller {
+  async update(post: Post) {
+    await this.authorize('update', post)
+
+    await post.update({ title: request().string('title').toString() })
+
+    return redirect().route('posts.show', post)
+  }
+}
+```
+
+`this.authorizeForUser(user, 'update', post)` checks the ability for another user. Gates and policies are covered on the
+[Authorization](authorization.md) page.
+
+## Generating controllers
+
+`make:controller` takes these options. Given several, `--model` wins over `--invokable`, and `--invokable` over
+`--resource`:
+
+| Option | What it writes |
+| --- | --- |
+| (none) | An empty controller |
+| `-i`, `--invokable` | A controller with an `__invoke()` method |
+| `-r`, `--resource` | The seven resource methods; the parameter is named after the controller, without its `Controller` suffix |
+| `--api` | The five API resource methods, without `create` and `edit` |
+| `-m`, `--model=Photo` | The resource methods typed with the model (with `--api`, the five); writes the model when it doesn't exist |
+| `-R`, `--requests` | With `--model`: the `Store` and `Update` form requests, and their `validate()` calls |
+| `--force` | Overwrites a controller that exists |
+
+A name with slashes writes into a subfolder: `make:controller Settings/ProfileController` writes
+`ProfileController.ts` in `app/Http/Controllers/Settings`, importing `../Controller`.

package/docs/csrf.md

@@ -0,0 +1,126 @@
+# CSRF protection
+
+Oriel protects your forms from cross-site request forgery: every form that changes something must send the
+session's CSRF token, or the request is refused.
+
+## Introduction
+
+Cross-site request forgery is an attack in which another site makes your users' browsers send requests to your app.
+Picture a `/user/email` route that accepts a `POST` and changes the signed-in user's email address. Without CSRF
+protection, any site the user visits could hold a form that posts its own address to that route, and submit it with
+a little JavaScript. The browser would send the user's session cookie along, and your app would change the address.
+
+To stop this, your app checks every `POST`, `PUT`, `PATCH` and `DELETE` request to a route in the `web` group for a
+secret value, the CSRF token, which only your own pages know.
+
+## Preventing CSRF requests
+
+Every session has a CSRF token. It is kept in the session, so another site can't read it, and it changes whenever the
+session is regenerated, as the starter kits do when a user signs in. Read it from the request's session, or with
+`csrfToken()`:
+
+```ts
+Route.get('/token', () => {
+  const token = request().session().token()
+
+  return csrfToken()
+})
+```
+
+A form you write yourself sends the token in a hidden `_token` field, which `csrfField()` writes:
+
+```tsx title="resources/views/profile.tsx"
+import { csrfField } from '@orieljs/framework'
+
+export default function Profile() {
+  return (
+    <form method="post" action="/profile">
+      {csrfField()}
+
+      {/* the same as <input type="hidden" name="_token" value={csrfToken()} autocomplete="off" /> */}
+      <button type="submit">Save</button>
+    </form>
+  )
+}
+```
+
+The `VerifyCsrfToken` middleware, in the `web` [middleware group](middleware.md#the-default-middleware-groups), checks
+that the token a request sends matches its session's. `GET`, `HEAD` and `OPTIONS` requests pass without one. A
+request whose token is missing or wrong gets a 419: the "Page Expired" page, or, when the request wants JSON,
+`{"message": "CSRF token mismatch."}`.
+
+[Inertia](inertia.md) pages and [Live](live.md) components send the token for you, from the `XSRF-TOKEN` cookie (see
+[X-XSRF-TOKEN](#x-xsrf-token)), so the starter kits' forms have no `_token` field.
+
+A form that should reach a `PUT`, `PATCH` or `DELETE` route posts with a hidden `_method` field as well, from
+`methodField()`: see [form method spoofing](routing.md#form-method-spoofing).
+
+### CSRF tokens and SPAs
+
+A single-page app served from your app's own domain sends the token in the `X-XSRF-TOKEN` header, as Inertia does. A
+frontend on another domain, or a mobile app, uses your API routes instead, which have no session and no CSRF check, and
+signs in with [personal access tokens](authentication.md#api-tokens). Oriel sends no CORS headers, so a browser frontend
+on another domain needs a middleware of your own that adds them.
+
+### Excluding URIs from CSRF protection
+
+Some routes can't get the token: a payment provider's webhook, for one, doesn't know it. Such routes are best kept out
+of the `web` group, in `routes/api.ts`. Otherwise, list their URIs in `validateCsrfTokens()` in `bootstrap/app.ts`:
+
+```ts
+Application.configure({ basePath: '.' }).withMiddleware((middleware) => {
+  middleware.validateCsrfTokens({
+    except: ['stripe/*', 'http://example.com/foo/bar', 'http://example.com/foo/*'],
+  })
+})
+```
+
+An entry is a path, with or without its leading `/`, or a full URL, and `*` matches anything. The same list can live
+in `csrf_except` in `config/http.ts`; `validateCsrfTokens()` adds to it. A single route can also leave the check out:
+`Route.post('/hooks/github', handler).withoutMiddleware(VerifyCsrfToken)`.
+
+> [!NOTE]
+> The check is skipped while your tests run: when the app runs in the console with `APP_ENV` set to `testing`, as the
+> `TestCase` of a new app sets it up (see [Testing](testing.md)). Your feature tests can post forms without a token.
+
+## X-CSRF-TOKEN
+
+`VerifyCsrfToken` also reads the token from an `X-CSRF-TOKEN` header. You can put the token in a `meta` tag in your
+layout:
+
+```tsx title="resources/views/partials/head.tsx"
+import { csrfToken } from '@orieljs/framework'
+
+export default function Head({ title }: { title: string }) {
+  return (
+    <head>
+      <title>{title}</title>
+      <meta name="csrf-token" content={csrfToken()} />
+    </head>
+  )
+}
+```
+
+and send it from your scripts:
+
+```ts title="resources/js/comments.ts"
+export function postComment(body: string): Promise<Response> {
+  const token = document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')?.content ?? ''
+
+  return fetch('/comments', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': token },
+    body: JSON.stringify({ body }),
+  })
+}
+```
+
+## X-XSRF-TOKEN
+
+Every response that passes `VerifyCsrfToken` carries the token in an `XSRF-TOKEN` cookie, encrypted as your other
+cookies are. The cookie isn't `HttpOnly`, so your scripts can read it, and a request may send its value back in an
+`X-XSRF-TOKEN` header, which `VerifyCsrfToken` decrypts. It takes its lifetime, path, domain, `secure` and `same_site`
+settings from `config/session.ts`.
+
+The cookie is there for the clients that send it on their own: Inertia's HTTP client and Live's client do, as
+Axios and Angular's `HttpClient` do.

package/docs/database-testing.md

@@ -0,0 +1,144 @@
+# Database testing
+
+Your tests can migrate a database for each test, fill it with factories and seeders, and check the rows your code
+wrote.
+
+## Introduction
+
+By default, each test runs on a new in-memory SQLite database (see [Environment](testing.md#environment)), which is
+empty: no tables until a test migrates it.
+
+### Resetting the database after each test
+
+`RefreshDatabase` gives each test a migrated database. Add it to the file's test case:
+
+```ts title="tests/Feature/Posts.test.ts"
+import { RefreshDatabase } from '@orieljs/framework/testing'
+import { test } from 'vitest'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot({ uses: [RefreshDatabase] })
+
+test('the posts page loads', async () => {
+  const response = await t.get('/posts')
+
+  response.assertOk()
+})
+```
+
+On the in-memory database, it runs your migrations for each test, on that test's new database. On a database in a
+file or on a server, it runs `migrate:fresh` once, and then runs each test inside a transaction that it rolls back
+afterwards, so no test sees another's rows.
+
+| Trait | What it does |
+| --- | --- |
+| `RefreshDatabase` | Migrates as above |
+| `DatabaseMigrations` | Runs `migrate:fresh` before each test and `migrate:rollback` after it |
+| `DatabaseTransactions` | Runs each test in a transaction that is rolled back, without migrating |
+
+To use a trait in every test, set it on your `TestCase`:
+
+```ts title="tests/TestCase.ts"
+import type { Application } from '@orieljs/framework'
+import { RefreshDatabase, TestCase as BaseTestCase } from '@orieljs/framework/testing'
+import { afterEach, beforeEach } from 'vitest'
+import { createApplication } from '../bootstrap/app'
+
+export class TestCase extends BaseTestCase {
+  static override hooks = { beforeEach, afterEach }
+
+  override readonly uses = [RefreshDatabase]
+
+  override createApplication(): Promise<Application> {
+    return createApplication()
+  }
+}
+```
+
+`connectionsToTransact` lists the connections the transaction traits wrap, the default one unless you name others.
+
+> [!NOTE]
+> Laravel's traits are PHP traits, added with `use RefreshDatabase;`. Oriel's are objects you list in `uses`.
+
+## Model factories
+
+[Factories](eloquent-factories.md) make the rows a test needs:
+
+```ts title="tests/Feature/Users.test.ts"
+import { RefreshDatabase } from '@orieljs/framework/testing'
+import { test } from 'vitest'
+import { User } from '../../app/Models/User'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot({ uses: [RefreshDatabase] })
+
+test('models can be instantiated', async () => {
+  const user = await User.factory().create()
+
+  const response = await t.actingAs(user).get('/dashboard')
+
+  response.assertOk()
+})
+```
+
+Oriel finds the factories in `database/factories` when your tests start.
+
+## Running seeders
+
+`t.runSeeder()` runs `DatabaseSeeder` in a test, or the seeder you name:
+
+```ts
+import { TestCase } from './tests/TestCase'
+const t = TestCase.boot()
+// ---cut---
+await t.runSeeder()
+
+await t.runSeeder('OrderStatusSeeder')
+```
+
+To seed before every test, set `seed`, or `seeder` for another seeder, on your `TestCase`. `RefreshDatabase` and
+`DatabaseMigrations` then seed after they migrate:
+
+```ts
+import { TestCase as BaseTestCase } from '@orieljs/framework/testing'
+// ---cut---
+export class TestCase extends BaseTestCase {
+  override seed = true
+}
+```
+
+> [!NOTE]
+> Laravel's `$this->seed()` is `runSeeder()` in Oriel, since `seed` is the option.
+
+## Available assertions
+
+The test case has these assertions. They read the database, so `await` each one:
+
+```ts
+import { TestCase } from './tests/TestCase'
+import type { User } from './app/Models/User'
+const t = TestCase.boot()
+declare const user: User
+// ---cut---
+await t.assertDatabaseHas('users', { email: 'sally@example.com' })
+
+await t.assertModelExists(user)
+```
+
+| Assertion | Passes when |
+| --- | --- |
+| `assertDatabaseHas(table, data)` | A row of the table has the values; `null` matches a null column |
+| `assertDatabaseMissing(table, data)` | No row has them |
+| `assertDatabaseCount(table, count)` | The table has that many rows |
+| `assertDatabaseEmpty(table)` | The table has no rows |
+| `assertModelExists(model)`, `assertModelMissing(model)` | The model's row is in the database, or isn't |
+| `assertSoftDeleted(tableOrModel, data?)`, `assertNotSoftDeleted(tableOrModel, data?)` | The row is soft deleted, or isn't |
+
+`table` is a table's name, or a model, whose table and connection the assertion uses. `assertDatabaseHas()`,
+`assertDatabaseMissing()`, `assertDatabaseCount()` and `assertDatabaseEmpty()` take a connection name as their last
+argument, and `assertSoftDeleted()` and `assertNotSoftDeleted()` after the data. A failed `assertDatabaseHas()` shows a
+few rows of the table, to help you see what differs.
+
+> [!NOTE]
+> Laravel's assertions also take a model's class, `User::class`. Oriel's take a table name or a model: write
+> `assertDatabaseHas('users', ...)`, or pass a model you have.