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

package/docs/lifecycle.md

@@ -0,0 +1,234 @@
+# Request lifecycle
+
+Oriel builds your app once, when its process starts, and answers every request from it, until the process ends and
+the app shuts down.
+
+## Introduction
+
+You can build an app without knowing how Oriel works inside. Knowing the order in which it does things tells you
+where your own code goes: what a service provider can rely on, when your routes exist, and what lasts longer than one
+request.
+
+## Lifecycle overview
+
+### First steps
+
+Your app has two entry points. `public/index.ts` starts the web server, as `node --import tsx public/index.ts` or
+`bun public/index.ts`, and `node oriel serve` starts the same server while you work. The `oriel` file runs a command,
+as `node oriel migrate`. Both get the application from `createApplication()` in `bootstrap/app.ts`:
+
+```ts title="public/index.ts"
+// @filename: bootstrap/app.ts
+export declare function createApplication(): Promise<import('@orieljs/framework').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())
+```
+
+`Application.configure()` creates the application, which is also the [service container](container.md). The methods
+after it record what you give them, and `create()` puts the app together:
+
+```ts title="bootstrap/app.ts"
+import { dirname } from 'node:path'
+import { Application } from '@orieljs/framework'
+import providers from './providers'
+
+/** Builds the application. Each call returns a fresh app (tests need one per test). */
+export function createApplication(): Promise<Application> {
+  return Application.configure({ basePath: dirname(import.meta.dirname) })
+    .withRouting({ web: 'routes/web.ts', console: 'routes/console.ts', health: '/up' })
+    .withProviders(providers)
+    .create()
+}
+```
+
+`create()` loads your `.env` file and every file in `config/` ([Configuration](configuration.md) covers both), then
+registers the service providers. Each call makes a new application, so your tests can have a fresh one for every test.
+
+### HTTP / console kernels
+
+A request goes to the HTTP kernel, and a command to the console kernel.
+
+`serve()` answers a `GET` or `HEAD` request for a file in `public/` itself, and hands every other request to
+`app.handle()`, which passes it to the HTTP kernel and returns the response. The kernel takes a web-standard `Request`
+and returns a `Response`: think of it as a black box that stands for your whole app. It wraps the request in Oriel's
+request object, applies the trusted proxies and the body limits of `config/http.ts` (see
+[Requests](requests.md#body-size-limits)), reads the body, and sends the request through the global middleware to the
+router.
+
+`node oriel` gives its arguments to the console kernel. The command runs, the app terminates as it does after a
+request, then it shuts down, and the process exits with the command's exit code.
+
+### Service providers
+
+Service providers set up every part of the framework: the database, the queue, validation, routing and the rest.
+`create()` calls each provider's `register()`, in order. The framework has 22, registered first, in this order:
+Pipeline, Encryption, Cookie, Session, Hashing, Log, Event, Cache, Filesystem, Database, Queue, Bus, Mail,
+Notifications, Validation, Auth, View, Inertia, Live, Routing, Http and Console (each one's class is its name followed
+by `ServiceProvider`). Each may rely on the ones before it. Yours come next, in the order `bootstrap/providers.ts`
+lists them.
+
+`create()` registers the providers but doesn't boot them. The app boots once, the first time something needs it:
+`serve()` before it starts listening, `node oriel` before it runs its command, your tests before each test, or the
+first request the app handles. Booting runs, in this order:
+
+1. the `booting()` callbacks;
+2. each provider's `boot()`, in the order they were registered. A provider registered while the app boots is booted in
+   the same pass, and one registered after it has booted is booted at once;
+3. the `booted()` callbacks, in the order they were added: those you give the builder first, then the framework's,
+   which add the health route, load the route files of `withRouting()` (the `web` files in the `web` group, then the
+   `api` files in the `api` group), apply your `withMiddleware()` callback and, in the console only, find your
+   commands; last, those your providers add in `boot()`.
+
+Your route files run once every provider has booted, so a route pattern, a binding or a gate that a provider sets up
+in `boot()` is ready for them. The builder takes callbacks of its own:
+
+```ts
+Application.configure({ basePath: '.' })
+  .booting((app) => {
+    // Before the first provider boots...
+  })
+  .booted((app) => {
+    // Once every provider has booted, before your routes load...
+  })
+```
+
+> [!NOTE]
+> Laravel bootstraps the application again for every request: a PHP process handles one request, then forgets it.
+> An Oriel app runs in a long-lived Node or Bun process, so it registers and boots its providers once, and serves
+> every request from the same application. A singleton lasts as long as the process; what belongs to one request lives
+> in that request's [scope](container.md#request-scopes).
+
+### Routing
+
+`app.handle()` opens a request scope, and the kernel binds the request in it: everything resolved for this request,
+such as the request, its session and its cookie jar, lives in the scope and is dropped with it. The global middleware
+run first: `TrimStrings`, `ConvertEmptyStringsToNull`, and those you add with
+[`withMiddleware()`](middleware.md#global-middleware).
+
+The router then finds the route. A path no route matches is a 404, and a path whose routes don't take the request's
+method is a 405 with an `Allow` header. The router records the route as the current one, then runs the route's
+middleware: those of its groups, outer group first, then its own. The routes in `routes/web.ts` are in the `web` group,
+which gives them their cookies, their session and CSRF protection:
+
+| The `web` group | What it does |
+| --- | --- |
+| `EncryptCookies` | Decrypts the request's cookies and encrypts the response's |
+| `AddQueuedCookiesToResponse` | Adds the cookies queued on the cookie jar to the response |
+| `StartSession` | Loads the session, and saves it once the response is ready |
+| `VerifyCsrfToken` | Refuses a form without the CSRF token |
+
+The `web` and `api` groups' middleware, `auth` and `guest` run before the route's other middleware, then route model
+binding replaces the parameters that name a model, then the rest run ([Sorting
+middleware](middleware.md#sorting-middleware) has the rule). Last, the action runs: a closure is called with the
+route's parameters, in URI order, and a controller is built by the container for this request. Whatever the action
+returns becomes the response, as [Responses](responses.md) describes.
+
+### Finishing up
+
+The response goes back out through the route's middleware, then the global middleware, each of which can examine or
+change it. An error thrown at any stage becomes a response at that stage, rendered by the exception handler (see
+[Error handling](errors.md)), so a middleware further out always receives a response. The response to a `HEAD`
+request loses its body here.
+
+The server writes the response, and then the app terminates the request, still inside its scope:
+
+1. `terminate()` runs on each [terminable middleware](middleware.md#terminable-middleware), the global ones first,
+   then the route's;
+2. the `terminating()` callbacks run, in the order they were added. One of them is the framework's: it runs the jobs
+   you dispatched with [`dispatchAfterResponse()`](queues.md#running-a-job-now).
+
+On Node, this starts once the response is written; on Bun, right after the response is handed to the server.
+
+Register a terminating callback in a service provider. It receives no arguments:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Services/Metrics.ts
+export declare class Metrics {
+  flush(): Promise<void>
+}
+// ---cut---
+import { ServiceProvider } from '@orieljs/framework'
+import { Metrics } from '../Services/Metrics'
+
+export class AppServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.app.singleton(Metrics)
+  }
+
+  override boot(): void {
+    this.app.terminating(async () => {
+      await this.app.make(Metrics).flush()
+    })
+  }
+}
+```
+
+> [!WARNING]
+> The terminating callbacks also run after each `node oriel` command, and after the server sends a file from
+> `public/`, which never reaches the app. They then run outside any request, where `request()` throws. A terminating
+> callback that throws stops the ones after it, and its error is printed to the console rather than reported; after a
+> command, `node oriel` then exits with code 1.
+
+## Shutting down
+
+A Node or Bun process keeps its database pools, its Redis clients and its log files open from one request to the next.
+When the process ends, `app.shutdown()` closes them: it runs the callbacks registered with `app.onShutdown()`, once.
+
+- The server calls it when it receives `SIGINT` or `SIGTERM`. It stops taking new connections, waits for the requests
+  in flight (closing the connections that are still open after 10 seconds), shuts the app down, and exits with 0.
+- `node oriel` calls it after its command, also when the command throws.
+- A script that makes the app itself must call it before it exits, or the last log entries are lost (see [Flushing
+  the log](logging.md#flushing-the-log)).
+
+The callbacks run newest first. Yours were registered after the framework's, so they run before the framework closes
+what they might use. Then the framework closes the queue's Redis connections, the database pools, the cache's Redis
+clients, the log files (writing out what is waiting) and the session's Redis connection, each only if your app opened
+it:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Services/Metrics.ts
+export declare class Metrics {
+  close(): Promise<void>
+}
+// ---cut---
+import { ServiceProvider } from '@orieljs/framework'
+import { Metrics } from '../Services/Metrics'
+
+export class AppServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.app.singleton(Metrics)
+
+    this.app.onShutdown(async () => {
+      if (this.app.resolved(Metrics)) await this.app.make(Metrics).close()
+    })
+  }
+}
+```
+
+A callback that throws is printed with `console.error`, and the others still run. If the callbacks haven't finished
+after 10 seconds, the rest are given up on, with "The shutdown callbacks did not finish within 10 seconds; carrying on
+with the exit.", so the process can still exit. `shutdown()` never rejects, and calling it again returns the same
+promise.
+
+| | `terminating()` | `onShutdown()` |
+| --- | --- | --- |
+| Runs | After each response, and after each `node oriel` command | Once, when the process ends |
+| Inside | The request's scope, after a request | No request |
+| Order | The order they were added | Newest first |
+| For | Work that waits until the response is sent | Closing pools, clients and files |
+
+> [!NOTE]
+> Laravel has no `onShutdown()`: PHP frees what a request opened when the request ends. An Oriel process serves many
+> requests, so the handles it opens stay open until the process ends, and `shutdown()` closes them before it exits.
+
+## Focus on service providers
+
+Service providers are the key to how an Oriel app starts: the application is created, the providers are registered and
+booted, and the requests are handed to the booted app. Your own providers live in `app/Providers`. A new app's
+`AppServiceProvider` is empty: it is the place for your app's bindings and its setup at boot. A larger app can split
+them over several providers, each listed in `bootstrap/providers.ts`. [Service providers](providers.md) explains how
+to write them.

package/docs/live-tests.md

@@ -0,0 +1,226 @@
+# Live tests
+
+`Live.test()` mounts a Live component in a test, calls its actions and checks its state and HTML. It goes through the
+same steps as the browser's updates, without a browser.
+
+## Creating your first test
+
+`make:live --test` writes a test with the component:
+
+```sh
+node oriel make:live Counter --test
+```
+
+The test, in `tests/Feature/Live`, mounts the component and checks its HTML:
+
+```ts title="tests/Feature/Live/Counter.test.ts"
+// @filename: app/Live/Counter.tsx
+import { Component } from '@orieljs/framework'
+export default class Counter extends Component {
+  count = 0
+  increment() {
+    this.count++
+  }
+  render() {
+    return <div>{this.count}</div>
+  }
+}
+// ---cut---
+import { Live } from '@orieljs/framework'
+import { expect, test } from 'vitest'
+import Counter from '../../../app/Live/Counter'
+import { TestCase } from '../../TestCase'
+
+TestCase.boot()
+
+test('counter renders', async () => {
+  const component = await Live.test(Counter)
+  expect(component.html()).toContain('<div')
+})
+```
+
+`Live.test()` needs the test's application, so boot the test case in the file.
+
+## Testing actions and properties
+
+`set()` sets a property, as an `o:model` input does, and `call()` calls an action, as `o:click` does. Both send an
+update, so `await` each one; the assertions that follow are synchronous and chain:
+
+```ts title="tests/Feature/Live/Counter.test.ts"
+// @filename: app/Live/Counter.tsx
+import { Component } from '@orieljs/framework'
+export default class Counter extends Component {
+  count = 0
+  increment() {
+    this.count++
+  }
+  render() {
+    return <div>{this.count}</div>
+  }
+}
+// ---cut---
+import { Live } from '@orieljs/framework'
+import { test } from 'vitest'
+import Counter from '../../../app/Live/Counter'
+import { TestCase } from '../../TestCase'
+
+TestCase.boot()
+
+test('the counter goes up', async () => {
+  const component = await Live.test(Counter)
+
+  await component.set('count', 5)
+  await component.call('increment')
+
+  component.assertSet('count', 6).assertSee('6')
+})
+```
+
+`set()` also takes several properties at once, `set({ title: 'Hello', body: 'World' })`, and `call()` the action's
+arguments after its name: `call('delete', 5)`. `toggle('open')` flips a boolean, `refresh()` renders the component
+again, and `dispatch('post-created', { id: 1 })` sends it an event, which its `@On` methods receive.
+
+The second argument of `Live.test()` is the mount parameters, as `<Live>` props would be:
+
+```ts
+// @filename: app/Live/Counter.tsx
+import { Component } from '@orieljs/framework'
+export default class Counter extends Component {
+  count = 0
+  render() {
+    return <div>{this.count}</div>
+  }
+}
+// ---cut---
+import Counter from './app/Live/Counter'
+
+const component = await Live.test(Counter, { count: 4 })
+```
+
+`get('count')` reads a property, `html()` the last HTML, `instance()` the component itself, and `effects()` what the
+last update asks of the browser, such as a redirect.
+
+### Authenticating
+
+`Live.test()` runs in the test's requests, so a user you gave `actingAs()` is signed in for the component:
+
+```ts title="tests/Feature/Live/Password.test.ts"
+// @filename: app/Live/Settings/Password.tsx
+import { Component } from '@orieljs/framework'
+export default class Password extends Component {
+  current_password = ''
+  password = ''
+  password_confirmation = ''
+  updatePassword() {}
+  render() {
+    return <form />
+  }
+}
+// ---cut---
+import { Hash, Live } from '@orieljs/framework'
+import { RefreshDatabase } from '@orieljs/framework/testing'
+import { expect, test } from 'vitest'
+import Password from '../../../app/Live/Settings/Password'
+import { User } from '../../../app/Models/User'
+import { TestCase } from '../../TestCase'
+
+const t = TestCase.boot({ uses: [RefreshDatabase] })
+
+test('password can be updated', async () => {
+  const user = await User.factory().create()
+
+  t.actingAs(user)
+  const component = await Live.test(Password)
+  await component.set({ current_password: 'password', password: 'new-password', password_confirmation: 'new-password' })
+  await component.call('updatePassword')
+
+  component.assertHasNoErrors().assertSet('password', '').assertDispatched('password-updated')
+
+  expect(await Hash.check('new-password', (await user.fresh())!.password)).toBe(true)
+})
+```
+
+What the component changes in the session, such as a sign-in, carries on to the test's next request, and the
+other way round.
+
+## Testing validation
+
+A failed validation leaves its errors on the component, which `assertHasErrors()` checks:
+
+```ts
+import type { Testable } from '@orieljs/framework/testing'
+declare const component: Testable
+// ---cut---
+await component.set('title', '')
+await component.call('save')
+
+component.assertHasErrors(['title'])
+```
+
+With no keys, `assertHasErrors()` passes when there is any error, and `assertHasNoErrors()` when there is none.
+`instance().errors.first('title')` reads a message.
+
+## Testing authorization
+
+An action that calls `abort(403)`, or whose policy check fails, throws in the test as it would end the request:
+
+```ts
+import type { Testable } from '@orieljs/framework/testing'
+import { expect } from 'vitest'
+declare const component: Testable
+// ---cut---
+await expect(component.call('delete', 5)).rejects.toMatchObject({ status: 403 })
+```
+
+A page route's `can` middleware runs on the page's own request, so check it with an [HTTP test](http-tests.md) of the
+page.
+
+## Testing redirects and events
+
+```ts
+import type { Testable } from '@orieljs/framework/testing'
+declare const component: Testable
+// ---cut---
+await component.call('save')
+
+component.assertRedirect('/posts').assertDispatched('post-created', { title: 'Hello' })
+```
+
+`assertRedirect()` with no URL passes on any redirect. `effects().redirectUsingNavigate` is `true` when the action
+asked for `{ navigate: true }`.
+
+## Testing file uploads
+
+In a `WithFileUploads` component, `set()` with a `FakeFile` uploads it as the browser would: through the upload rules,
+to the temporary disk, and into the property as a `TemporaryUploadedFile`:
+
+```ts
+import { FakeFile, type Testable } from '@orieljs/framework/testing'
+declare const component: Testable
+// ---cut---
+await component.set('photo', FakeFile.image('photo.jpg'))
+await component.call('save')
+
+component.assertHasNoErrors()
+```
+
+An array of files sets a `multiple` input's property. A file that fails `live.temporary_file_upload.rules` leaves the
+upload's error on the property. Use `Storage.fake()` to check where `store()` puts the file.
+
+## Available assertions
+
+| Assertion | Passes when |
+| --- | --- |
+| `assertSet(name, value)`, `assertNotSet(name, value)` | The property has the value, or hasn't |
+| `assertSee(...texts)`, `assertDontSee(...texts)` | The HTML has each text, escaped as the HTML writes it |
+| `assertSeeHtml(...html)` | The HTML has each piece of HTML, as it is |
+| `assertSeeText(...texts)`, `assertDontSeeText(...texts)` | The text, with the tags taken out, has each text |
+| `assertHasErrors(keys?)`, `assertHasNoErrors(keys?)` | The component has errors for the keys, or has none |
+| `assertDispatched(name, params?)`, `assertNotDispatched(name)` | The last update dispatched the event, with those parameters |
+| `assertRedirect(url?)`, `assertNoRedirect()` | The last update redirects, to that URL |
+| `assertReturned(value)` | The last action returned the value |
+
+> [!NOTE]
+> Livewire's `assertSeeLivewire()`, `assertViewHas()`, `assertCount()` and `withQueryParams()` aren't in Oriel. To
+> check that a page has a component, check the page's HTML with an HTTP test; `get()` and Vitest's `expect()` check
+> the rest.