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

package/docs/errors.md

@@ -0,0 +1,318 @@
+# Error handling
+
+When a request ends in an error, Oriel logs it if it should and answers with an error page or JSON.
+`withExceptions()` changes both.
+
+## Introduction
+
+A new app handles errors with no setup: an unexpected error that a route or a middleware throws is reported to your
+log, and the user gets a response with the error's status. To change how errors are reported and rendered, give
+`withExceptions()` in `bootstrap/app.ts` a function that receives the configurator, as the rest of this page shows.
+
+## Configuration
+
+`debug` in `config/app.ts` decides how much an error response shows. It reads `APP_DEBUG` from your `.env` (see [Debug
+mode](configuration.md#debug-mode)), and is `false` unless the variable says otherwise:
+
+```ts title="config/app.ts"
+import { env } from '@orieljs/framework'
+
+export default {
+  name: env('APP_NAME', 'Oriel'),
+  env: env('APP_ENV', 'production'),
+  debug: env('APP_DEBUG', false),
+  url: env('APP_URL', 'http://localhost'),
+  timezone: 'UTC',
+  locale: env('APP_LOCALE', 'en'),
+  cipher: 'AES-256-GCM',
+  key: env('APP_KEY'),
+  previous_keys: String(env('APP_PREVIOUS_KEYS', '')).split(',').filter(Boolean),
+}
+```
+
+A new app's `.env` sets `APP_DEBUG=true`, for your machine. With it, a server error shows the debug page: the error's
+class and message, the request's method and URL, the lines of your code around where it was thrown, the stack, and
+the errors that caused it. A request that expects JSON gets the message, the error's name, the file, the line and
+the stack. Errors with an HTTP status, such as a 404, get their usual page either way.
+
+> [!WARNING]
+> In production, `APP_DEBUG` must be `false`. The debug page shows your code and your error messages, which can hold
+> configuration values and other secrets, to anyone who triggers an error.
+
+## Handling exceptions
+
+### Reporting exceptions
+
+Reporting an error writes it to your [log](logging.md), at the `error` level, with the error itself as the entry's
+`exception` context. `report()` registers a function that receives each error to report, to send it somewhere else
+too, such as an error tracking service:
+
+```ts title="bootstrap/app.ts"
+// @filename: app/Exceptions/InvalidOrderException.ts
+export class InvalidOrderException extends Error {}
+// ---cut---
+import { dirname } from 'node:path'
+import { Application } from '@orieljs/framework'
+import { InvalidOrderException } from '../app/Exceptions/InvalidOrderException'
+import providers from './providers'
+
+export function createApplication(): Promise<Application> {
+  return Application.configure({ basePath: dirname(import.meta.dirname) })
+    .withRouting({ web: 'routes/web.ts', console: 'routes/console.ts', health: '/up' })
+    .withExceptions((exceptions) => {
+      exceptions.report((error) => {
+        if (error instanceof InvalidOrderException) {
+          // ...
+        }
+      })
+    })
+    .withProviders(providers)
+    .create()
+}
+```
+
+The error is still logged afterwards. Return `false` from the function to stop that, and the functions registered
+after it:
+
+```ts
+declare const exceptions: ExceptionsConfigurator
+declare class InvalidOrderException extends Error {}
+// ---cut---
+exceptions.report((error) => {
+  if (error instanceof InvalidOrderException) {
+    // ...
+
+    return false
+  }
+})
+```
+
+> [!NOTE]
+> Laravel calls a `report()` function only for the errors of the class its parameter type-hints. TypeScript types are
+> gone when your app runs, so Oriel calls every function for every error it reports: check the error's class with
+> `instanceof`, as above.
+
+Each error is reported once, however many times it reaches the handler, as in Laravel after `dontReportDuplicates()`.
+Laravel's global and per-exception log context, `context()`, isn't in Oriel; [Logging](logging.md) shows how to add
+context to every log entry.
+
+#### Reporting an error yourself
+
+Oriel has no `report()` helper. To report an error and carry on with the request, call the exception handler's
+`report()`:
+
+```ts
+declare function validateTheValue(value: string): void
+// ---cut---
+async function isValid(value: string): Promise<boolean> {
+  try {
+    validateTheValue(value)
+
+    return true
+  } catch (error) {
+    await app().make(ExceptionHandler).report(error)
+
+    return false
+  }
+}
+```
+
+### Exception log levels
+
+Every report is logged at the `error` level. Laravel's `level()`, which changes the level by the error's class, isn't
+in Oriel: log the error yourself from a `report()` function, at the level you want, and return `false`.
+
+### Ignoring exceptions by type
+
+`dontReport()` takes the error classes never to report. They are still rendered as usual:
+
+```ts
+declare const exceptions: ExceptionsConfigurator
+declare class InvalidOrderException extends Error {}
+// ---cut---
+exceptions.dontReport(InvalidOrderException)
+```
+
+Oriel never reports the errors that are part of normal requests: an `abort()`, a missing route or model, a failed
+validation, an unauthenticated or unauthorized user, and a CSRF token mismatch. Laravel's `dontReportWhen()`,
+`stopIgnoring()` and `ShouldntReport` interface aren't in Oriel.
+
+### Rendering exceptions
+
+`render()` registers a function that turns an error into a response. It receives the error and the request, and
+returns a `Response`, or nothing to leave the error to the default rendering:
+
+```ts title="bootstrap/app.ts"
+// @filename: app/Exceptions/InvalidOrderException.ts
+export class InvalidOrderException extends Error {}
+// ---cut---
+import { dirname } from 'node:path'
+import { Application, response, View } from '@orieljs/framework'
+import { InvalidOrderException } from '../app/Exceptions/InvalidOrderException'
+import providers from './providers'
+
+export function createApplication(): Promise<Application> {
+  return Application.configure({ basePath: dirname(import.meta.dirname) })
+    .withRouting({ web: 'routes/web.ts', console: 'routes/console.ts', health: '/up' })
+    .withExceptions((exceptions) => {
+      exceptions.render(async (error) => {
+        if (error instanceof InvalidOrderException) {
+          return response(await View.make('errors.invalid-order').render(), 500)
+        }
+      })
+    })
+    .withProviders(providers)
+    .create()
+}
+```
+
+The functions run first, for every error, so they can change how a built-in error renders too:
+
+```ts
+declare const exceptions: ExceptionsConfigurator
+// ---cut---
+exceptions.render((error, request) => {
+  if (error instanceof ModelNotFoundError && (request as HttpRequest).is('api/*')) {
+    return response().json({ message: 'Record not found.' }, 404)
+  }
+})
+```
+
+The request is typed `unknown`: during a request it is the request `request()` returns.
+
+#### Rendering exceptions as JSON
+
+An error is rendered as JSON when the request expects JSON: its `Accept` header asks for JSON first, or it is an
+AJAX request that accepts anything (see [content negotiation](requests.md#content-negotiation)). Otherwise it gets
+an HTML page. With `shouldRenderJsonWhen()`, you decide it yourself; the API starter kit answers JSON for every route
+under `/api`:
+
+```ts
+declare const exceptions: ExceptionsConfigurator
+// ---cut---
+exceptions.shouldRenderJsonWhen((request) => request.is('api/*') || request.expectsJson())
+```
+
+Laravel's `respond()`, which changes every response the handler renders, isn't in Oriel: use `render()`.
+
+### Renderable exceptions
+
+An error class of your own can render itself. Give it a `render()` method that returns a `Response`:
+
+```ts title="app/Exceptions/InvalidOrderException.ts"
+import { response } from '@orieljs/framework'
+
+export class InvalidOrderException extends Error {
+  /** Render the exception as an HTTP response. */
+  render(request: unknown): Response {
+    return response('The order could not be processed.', 422)
+  }
+}
+```
+
+When `render()` returns something that isn't a `Response`, the error is rendered as usual. A `toResponse()` method
+works the same way. The error is still reported, unless its class is in `dontReport()`. Laravel's reportable
+exceptions, with a `report()` method of their own, aren't in Oriel: use a `report()` function in `withExceptions()`.
+
+Laravel's `throttle()`, which samples or rate limits the reports, isn't in Oriel either.
+
+## HTTP exceptions
+
+`abort()` ends the request with an HTTP status, from anywhere in your code:
+
+```ts
+abort(404)
+```
+
+A message and headers can follow. The message is what JSON responses show; the HTML pages show it for a 403 only:
+
+```ts
+abort(403, 'You may not edit this post.')
+
+abort(503, 'Down for maintenance', { 'Retry-After': '120' })
+```
+
+`abortIf()` and `abortUnless()` abort when a condition is true, or false:
+
+```ts
+declare const user: User | undefined
+declare const post: Post
+// ---cut---
+abortIf(user === undefined, 403)
+
+abortUnless(post.published_at !== null, 404)
+```
+
+`abort()` also takes a ready `Response`, which is sent as it is: `abort(response('Gone fishing', 418))`.
+
+### Statuses by error
+
+Oriel's own errors carry their statuses. Each gets the same page, or JSON, as an `abort()` with that status:
+
+| Error | Status |
+| --- | --- |
+| No route matches the URL | 404 |
+| The route doesn't take the method | 405, with an `Allow` header |
+| A model not found, by `findOrFail()` or [route model binding](routing.md#route-model-binding) | 404 |
+| A guest on a route with the `auth` middleware | 401 as JSON; otherwise a redirect to the login page |
+| An authorization check that fails | 403, or the status the policy chose |
+| A form without its [CSRF token](csrf.md) | 419 |
+| A failed [validation](validation.md) | 422 as JSON; otherwise a redirect back with the errors |
+| Too many requests on a `throttle` route | 429, with `Retry-After` and the `X-RateLimit-*` headers |
+| A body over the [size limit](requests.md#body-size-limits) | 413 |
+| A JSON body nested too deeply | 400 |
+| Anything else | 500 |
+
+None of these is reported, except the last. The login page a guest is sent to is `http.redirect_guests_to`, set with
+[`redirectGuestsTo()`](middleware.md#redirecting-guests-and-signed-in-users), else the route named `login`, else
+`/login`; the URL the guest wanted is kept for after they sign in.
+
+### Custom HTTP error pages
+
+To show your own page for a status, add a view named after it: `resources/views/errors/404.tsx` for a 404. The view
+receives the `status`, the `message` and the `exception`:
+
+```tsx title="resources/views/errors/404.tsx"
+interface Props {
+  status: number
+  message: string
+  exception: unknown
+}
+
+export default function NotFound({ status, message, exception }: Props) {
+  return (
+    <html lang="en">
+      <body>
+        <h1>{status}</h1>
+        <h2>{exception instanceof Error && exception.message !== '' ? exception.message : message}</h2>
+      </body>
+    </html>
+  )
+}
+```
+
+`message` is the status's text, "Not Found", except for a 403, where it is the error's message. The error's own
+message is on `exception`, and is empty for an `abort(404)` without one. A new app has no error views. Without one,
+the page is a minimal one with the status and its text, as `404 | Not Found`.
+
+The pages are views like any other, so they can use your layout. A view that fails to render is reported, and the
+minimal page is sent in its place.
+
+#### Fallback HTTP error pages
+
+`resources/views/errors/4xx.tsx` is the page for any client error without a page of its own, and `5xx.tsx` for any
+server error.
+
+> [!NOTE]
+> Laravel's fallback pages don't cover 404, 500 and 503, which have pages of their own inside the framework. Oriel
+> has none of those, so `4xx.tsx` and `5xx.tsx` cover every status without its own view.
+
+### What a production error shows
+
+With `debug` off, a server error shows nothing of the error: your `errors/500.tsx` or `errors/5xx.tsx` view, or the
+minimal "500 | Server Error", and `{ "message": "Server Error" }` to a request that expects JSON. The error is
+reported to your log with its stack.
+
+An error with an HTTP status shows its status text on the HTML page (a 403 shows its message), and its message in
+JSON: `{ "message": "No query results for model [Post] 5" }` for a missing `Post`. Keep secrets out of the messages
+you give `abort()`.

package/docs/events.md

@@ -0,0 +1,336 @@
+# Events
+
+Events let one part of your app announce that something happened, and let other parts act on it, without the two
+knowing about each other.
+
+## Introduction
+
+An event is a plain class that carries what happened: an `OrderShipped` event carries the order. A listener is a
+class with a `handle()` method that the event is passed to. One event can have many listeners: when an order ships,
+one listener emails the customer and another tells the warehouse, and the code that ships the order dispatches the
+event and knows about neither.
+
+Events live in `app/Events` and listeners in `app/Listeners`. Neither folder exists in a new app: the `make:event` and
+`make:listener` commands create them.
+
+## Generating events and listeners
+
+```sh
+node oriel make:event OrderShipped
+node oriel make:listener SendShipmentNotification --event=OrderShipped
+```
+
+`make:listener` with `--event` writes a listener that already names its event in `static listensTo`, so
+[discovery](#event-discovery) registers it. Add `--queued` for a [queued listener](#queued-event-listeners).
+
+## Registering events and listeners
+
+### Event discovery
+
+When your app boots, Oriel imports every file under `app/Listeners`, folders included, and registers each exported
+class that has a `handle()` method and a static `listensTo` field. `listensTo` names the event the listener handles:
+an event class, an event's name as a string, or an array of either.
+
+```ts title="app/Listeners/SendShipmentNotification.ts"
+// @filename: app/Events/OrderShipped.ts
+import type { Order } from '../Models/Order'
+export class OrderShipped {
+  constructor(readonly order: Order) {}
+}
+// ---cut---
+import { OrderShipped } from '../Events/OrderShipped'
+
+export class SendShipmentNotification {
+  static listensTo = OrderShipped
+
+  async handle(event: OrderShipped): Promise<void> {
+    // Email the customer about event.order...
+  }
+}
+```
+
+Any other export in a listener's file, such as a helper function, is skipped.
+
+> [!NOTE]
+> Laravel finds a listener's event from the type of its `handle()` method's parameter. TypeScript types are gone when
+> your app runs, so an Oriel listener names its event in `static listensTo`. A listener without it isn't discovered:
+> register it yourself.
+
+A new app has no `config/events.ts`. To turn discovery off, add one: `export default { discover: false }`.
+
+### Manually registering events
+
+`Event.listen()` registers a listener in a provider's `boot()` method. The listener can be a listener class, a
+`[class, method]` pair, or a function:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Events/OrderShipped.ts
+import type { Order } from '../Models/Order'
+export class OrderShipped {
+  constructor(readonly order: Order) {}
+}
+// @filename: app/Listeners/SendShipmentNotification.ts
+import type { OrderShipped } from '../Events/OrderShipped'
+export declare class SendShipmentNotification {
+  handle(event: OrderShipped): Promise<void>
+}
+// ---cut---
+import { Event, ServiceProvider } from '@orieljs/framework'
+import { OrderShipped } from '../Events/OrderShipped'
+import { SendShipmentNotification } from '../Listeners/SendShipmentNotification'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Event.listen(OrderShipped, SendShipmentNotification)
+
+    Event.listen(OrderShipped, (event: OrderShipped) => {
+      // ...
+    })
+  }
+}
+```
+
+A listener class registered here and also discovered runs twice, once for each registration.
+
+`config/events.ts` can list them too, under `listen`, as `[event, listeners]` pairs (a TypeScript object can't take a
+class as a key):
+
+```ts title="config/events.ts"
+// @filename: app/Events/OrderShipped.ts
+import type { Order } from '../Models/Order'
+export class OrderShipped {
+  constructor(readonly order: Order) {}
+}
+// @filename: app/Listeners/SendShipmentNotification.ts
+import type { OrderShipped } from '../Events/OrderShipped'
+export declare class SendShipmentNotification {
+  handle(event: OrderShipped): Promise<void>
+}
+// ---cut---
+import type { EventListenMap } from '@orieljs/framework'
+import { OrderShipped } from '../app/Events/OrderShipped'
+import { SendShipmentNotification } from '../app/Listeners/SendShipmentNotification'
+
+export default {
+  discover: true,
+  listen: [[OrderShipped, [SendShipmentNotification]]] as EventListenMap,
+}
+```
+
+#### Wildcard listeners
+
+A listener for a string event can use `*` as a wildcard. It is called with the event's name and the array of its
+payload:
+
+```ts
+import { Event } from '@orieljs/framework'
+
+Event.listen('order.*', (eventName: string, payload?: unknown[]) => {
+  // ...
+})
+```
+
+### Viewing the events
+
+`event:list` lists every event with how many listeners it has:
+
+```sh
+node oriel event:list
+```
+
+## Defining events
+
+An event holds the data its listeners need, and nothing else:
+
+```ts title="app/Events/OrderShipped.ts"
+import type { Order } from '../Models/Order'
+
+export class OrderShipped {
+  constructor(readonly order: Order) {}
+}
+```
+
+## Defining listeners
+
+A listener's `handle()` method takes the event. It may be async; the dispatch waits for it before it calls the next
+listener.
+
+Your app builds a listener class with its container each time the event is dispatched. It is built by the application,
+not by the request's scope, so an `inject()` of a request-scoped service in a listener's field throws during a request.
+Call `inject()` inside `handle()` instead.
+
+### Stopping the propagation of an event
+
+A listener that returns `false` stops the listeners after it from running.
+
+## Queued event listeners
+
+A listener that sends email or calls another service can run on the queue instead, so the request doesn't wait for it.
+Give it a `readonly shouldQueue = true` field, as `make:listener --queued` does:
+
+```ts title="app/Listeners/SendShipmentNotification.ts"
+// @filename: app/Events/OrderShipped.ts
+import type { Order } from '../Models/Order'
+export class OrderShipped {
+  constructor(readonly order: Order) {}
+}
+// ---cut---
+import type { ShouldQueue } from '@orieljs/framework/contracts'
+import { OrderShipped } from '../Events/OrderShipped'
+
+export class SendShipmentNotification implements ShouldQueue {
+  static listensTo = OrderShipped
+
+  readonly shouldQueue = true
+
+  async handle(event: OrderShipped): Promise<void> {
+    // ...
+  }
+}
+```
+
+When the event is dispatched, the listener is pushed to the queue as a job, with the event, and a worker
+(`node oriel queue:work`) runs it. The queue component must be in your app; read the [Queues](queues.md) page for
+workers and connections.
+
+### Customizing the queue connection, name and delay
+
+A queued listener takes the job options as fields: `connection`, `queue`, `delay`, `tries`, `backoff` and `timeout`.
+Each can be a method that returns the value. A listener with any of these fields is queued even without
+`shouldQueue`.
+
+```ts
+export class SendShipmentNotification {
+  readonly shouldQueue = true
+  readonly connection = 'redis'
+  readonly queue = 'listeners'
+  readonly delay = 60
+
+  async handle(): Promise<void> {
+    // ...
+  }
+}
+```
+
+### Unique listeners
+
+A queued listener with a `uniqueId()` method is unique (so is one with `uniqueFor`, `uniqueUntilProcessing` or
+`uniqueVia()`, whose id is then empty): while one of its jobs is waiting or running, another dispatch with the same id
+isn't queued. `uniqueId()` is called with the event, when the event is dispatched:
+
+```ts title="app/Listeners/SendShipmentNotification.ts"
+// @filename: app/Events/OrderShipped.ts
+import type { Order } from '../Models/Order'
+export class OrderShipped {
+  constructor(readonly order: Order) {}
+}
+// ---cut---
+import { OrderShipped } from '../Events/OrderShipped'
+
+export class SendShipmentNotification {
+  static listensTo = OrderShipped
+
+  readonly shouldQueue = true
+  readonly uniqueFor = 3600
+
+  uniqueId(event: OrderShipped): string {
+    return String(event.order.getKey())
+  }
+
+  async handle(event: OrderShipped): Promise<void> {
+    // ...
+  }
+}
+```
+
+A duplicate is a second job for the same listener class with the same id. The lock is the listener's, by class: the
+same class listening to two events, or through two methods of a [subscriber](#event-subscribers), shares one lock
+for each id. `uniqueFor` is how many seconds the lock lasts at most, and `uniqueUntilProcessing = true` releases it
+when the job starts rather than when it ends. The lock is a cache lock, so your app's cache store must support locks
+(read the Cache page's [Atomic locks](cache.md#atomic-locks)); `uniqueVia()` returns another store's name.
+
+> [!NOTE]
+> Laravel 12 has no unique listeners; Laravel 13 adds them. Oriel's work as Laravel 13's do, and as
+> [unique jobs](queues.md#unique-jobs).
+
+## Dispatching events
+
+`Event.dispatch()` dispatches an event, and the `event()` helper does the same. Both wait for every listener that
+isn't queued, and give back the listeners' return values:
+
+```ts
+// @filename: app/Events/OrderShipped.ts
+import type { Order } from '../Models/Order'
+export class OrderShipped {
+  constructor(readonly order: Order) {}
+}
+// ---cut---
+import { Event, event } from '@orieljs/framework'
+import { OrderShipped } from './app/Events/OrderShipped'
+import { Order } from './app/Models/Order'
+
+const order = await Order.findOrFail(1)
+
+await Event.dispatch(new OrderShipped(order))
+await event(new OrderShipped(order))
+```
+
+A string event takes its payload as an array, which its listeners receive as arguments:
+`Event.dispatch('order.shipped', [order])`. `Event.until()` stops at the first listener that returns something other
+than `undefined`, and gives back that value.
+
+## Event subscribers
+
+A subscriber is one class that listens to several events. Its `subscribe()` method returns a map of event names to the
+method, or methods, that handle them:
+
+```ts title="app/Listeners/UserEventSubscriber.ts"
+export class UserEventSubscriber {
+  handleUserLogin(): void {
+    // ...
+  }
+
+  handleUserLogout(): void {
+    // ...
+  }
+
+  subscribe(): Record<string, string> {
+    return {
+      'user.login': 'handleUserLogin',
+      'user.logout': 'handleUserLogout',
+    }
+  }
+}
+```
+
+The map's keys are strings, so they name string events. For class events, `subscribe()` takes the dispatcher and can
+call its `listen()` with `[UserEventSubscriber, 'handleUserLogin']` pairs. Register a subscriber in a provider's
+`boot()`, with `Event.subscribe(UserEventSubscriber)`; discovery doesn't find subscribers.
+
+## Testing
+
+`Event.fake()` swaps the dispatcher for a fake that records events instead of running their listeners. Give it the
+events to fake, and the others still run:
+
+```ts
+// @filename: app/Events/OrderShipped.ts
+import type { Order } from '../Models/Order'
+export class OrderShipped {
+  constructor(readonly order: Order) {}
+}
+// ---cut---
+import { Event } from '@orieljs/framework'
+import { OrderShipped } from './app/Events/OrderShipped'
+
+const events = Event.fake([OrderShipped])
+
+// Ship the order...
+
+events.assertDispatched(OrderShipped)
+events.assertDispatchedTimes(OrderShipped, 1)
+events.assertNotDispatched('order.cancelled')
+```
+
+The fake also has `assertNothingDispatched()`, `assertListening(event, listener)` and `dispatched(event)`.
+`EventFake.fakeExcept([OrderShipped])`, from `@orieljs/framework/testing`, fakes every event but the ones you list.
+[Fakes](mocking.md) covers fakes in full.