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

package/docs/facades.md

@@ -0,0 +1,278 @@
+# Facades
+
+Facades give you Oriel's services by name, as `Cache.get('key')`, resolved from the current request or the
+application each time you use them.
+
+## Introduction
+
+Code throughout these pages reaches Oriel's features through facades. A facade gives you a service of the [service
+container](container.md) under a short name, as if its methods were static, and forwards each call to the service the
+container holds. Oriel has a facade for most of its features, and exports them all from `@orieljs/framework`:
+
+```ts title="routes/web.ts"
+import { Cache, Route } from '@orieljs/framework'
+
+Route.get('/cache', () => Cache.get('key'))
+```
+
+#### Helper functions
+
+Alongside the facades, Oriel has helper functions for the features you use most: `view()`, `response()`, `config()`,
+`request()`, `session()` and others. Each feature's page documents its helper, and [Helpers](helpers.md) lists them all.
+A helper and its facade reach the same service, so these two are the same:
+
+```ts
+const fromFacade = View.make('profile')
+
+const fromHelper = view('profile')
+```
+
+## When to use facades
+
+Facades are short to write: a feature's name, then its method, with nothing to inject or configure. Because they ask
+for nothing, a class can come to use many of them, and grow past one job without you noticing. When a class reaches
+for many facades, consider splitting it into smaller classes.
+
+### Facades vs. dependency injection
+
+A service you inject can be replaced in a test by a stand-in. A facade's service can be replaced the same way, since the
+facade resolves it from the container at each call: your tests give the container a fake, and the code under test uses
+it through the facade.
+
+The facades of the services you most often check in a test have a `fake()`: `Mail.fake()`, `Queue.fake()`,
+`Bus.fake()`, `Event.fake()`, `Storage.fake()` and `Notification.fake()`. Each puts a fake in place of the service
+and returns it, and you check what your code did on the fake it returned:
+
+```ts title="tests/Feature/ShipOrder.test.ts"
+// @filename: tests/TestCase.ts
+import { TestCase as BaseTestCase } from '@orieljs/framework/testing'
+export class TestCase extends BaseTestCase {}
+// @filename: app/Mail/OrderShipped.ts
+import { Mailable } from '@orieljs/framework'
+export class OrderShipped extends Mailable {}
+// ---cut---
+import { Mail } from '@orieljs/framework'
+import { test } from 'vitest'
+import { OrderShipped } from '../../app/Mail/OrderShipped'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot()
+
+test('shipping an order sends the mail', async () => {
+  const mail = Mail.fake()
+
+  await t.post('/orders/1/ship')
+
+  mail.assertSent(OrderShipped)
+})
+```
+
+`Storage.fake('avatars')` returns the fake disk. [Fakes](mocking.md) lists every fake and its assertions.
+
+For any other facade, `swap()` puts an object of your own in place of the service:
+
+```ts title="tests/Feature/PublishPodcast.test.ts"
+// @filename: tests/TestCase.ts
+import { TestCase as BaseTestCase } from '@orieljs/framework/testing'
+export class TestCase extends BaseTestCase {}
+// @filename: app/Facades/Podcasts.ts
+import { facade } from '@orieljs/framework'
+export declare class PodcastPublisher {
+  publish(podcast: import('../Models/Podcast').Podcast): Promise<void>
+}
+export const Podcasts = facade(PodcastPublisher)
+// ---cut---
+import { RefreshDatabase } from '@orieljs/framework/testing'
+import { expect, test } from 'vitest'
+import { Podcasts } from '../../app/Facades/Podcasts'
+import { Podcast } from '../../app/Models/Podcast'
+import { TestCase } from '../TestCase'
+
+const t = TestCase.boot({ uses: [RefreshDatabase] })
+
+test('a podcast can be published', async () => {
+  const podcast = await Podcast.create({ title: 'Episode 1', audio_path: 'podcasts/1.mp3' })
+  const published: number[] = []
+  Podcasts.swap({ publish: async (episode) => void published.push(episode.id) })
+
+  await t.post(`/podcasts/${podcast.id}/publish`)
+
+  expect(published).toEqual([podcast.id])
+})
+```
+
+`swap()` binds the object as an instance on the current container. In a test, outside any request, that is the test's
+application, so every request the test makes uses it. Inside a request, it replaces the service for that request
+only.
+
+> [!NOTE]
+> Laravel's facades can be mocked with Mockery: `Cache::shouldReceive('get')`, `spy()`, `partialMock()`. Oriel's
+> have no mocking methods. Use the facade's `fake()` where it has one, and `swap()` with a stand-in of your own
+> otherwise.
+
+### Facades vs. helper functions
+
+A helper does what its facade does: `view('profile')` and `View.make('profile')` both ask the view factory for the
+view. Both resolve the same service from the container, so a fake or a `swap()` reaches the code that uses the
+helper too:
+
+```ts
+Route.get('/cache', () => cache('key'))
+```
+
+`cache('key')` calls `get()` on the cache manager the `Cache` facade stands for, so a test that swaps the `Cache`
+facade's service changes what this route returns.
+
+## How facades work
+
+A facade is an object that `facade()` makes from a class or a
+[token](container.md#binding-interfaces-to-implementations). Each time you read one of its properties, it resolves the
+service from the current container and returns the service's property, its methods bound to the service. The current
+container is the one `inject()` uses (see [Injecting with `inject()`](container.md#injecting-with-inject)): inside a
+request, a queued job or a command, its scope; otherwise, the application. So `Session` reaches the current request's
+session, and `Mail` the mail manager your app shares.
+
+You can make a facade for a service of your own:
+
+```ts title="app/Facades/Podcasts.ts"
+// @filename: app/Services/PodcastPublisher.ts
+export declare class PodcastPublisher {
+  publish(podcast: import('../Models/Podcast').Podcast): Promise<void>
+}
+// ---cut---
+import { facade } from '@orieljs/framework'
+import { PodcastPublisher } from '../Services/PodcastPublisher'
+
+export const Podcasts = facade(PodcastPublisher)
+```
+
+From then on, `Podcasts.publish(podcast)` calls `publish()` on the `PodcastPublisher` the container gives you, a new
+one each time unless you bind it as a singleton. `facade()` takes a second argument, an object of extra methods,
+which is how `Mail` has `fake()` and `Hash` has `driver()`.
+
+> [!NOTE]
+> A Laravel facade is a class whose `getFacadeAccessor()` names a binding, and whose static calls `__callStatic()`
+> forwards to it. Oriel's is an object made by `facade()`, which forwards every property you read, and needs no
+> class of its own.
+
+### Typing
+
+A facade is typed as the service it stands for, with its extra methods and two of its own: `getFacadeRoot()`, which
+returns the service, and `swap()`. TypeScript checks every call:
+
+```ts
+Route.get('/podcasts', () => 'Podcasts')
+
+// @ts-expect-error: the router has no post2()
+Route.post2('/podcasts', () => 'Created')
+```
+
+`Route` is typed as Oriel's router, so a misspelt method or a wrong argument fails the type check, and your editor
+completes the facade's methods. The `Facade<T>` type, exported from `@orieljs/framework`, names the type of a facade
+you write yourself.
+
+### Facades at a module's top level
+
+A facade resolves its service when you use it, so it works only while your app is running. Don't use one at a
+module's top level, outside any function:
+
+```ts title="app/Services/Greeting.ts"
+import { Config } from '@orieljs/framework'
+
+// Runs when the module is first imported: before your app exists, this throws.
+const appName = Config.string('app.name')
+
+export function greeting(): string {
+  return `Welcome to ${appName}`
+}
+```
+
+A module's top level runs once, when the module is first imported. Your providers, and what they import, are imported
+with `bootstrap/app.ts`, before `createApplication()` has made the app, and a test file's imports run before its first
+test has an app. Then no container is available, and the facade throws a `ContainerNotAvailableError`: "Cannot resolve
+[Config.Repository]: no container is available. inject(), helpers and facades only work while the application is
+running (inside a request, job, command, provider or app.run()). Don't call them at module top level."
+
+When an app does exist, the top level resolves that app's service, once, and keeps it: your tests make a new app for
+each test, and every test would see the first test's value. Use the facade inside the function instead:
+
+```ts title="app/Services/Greeting.ts"
+import { Config } from '@orieljs/framework'
+
+export function greeting(): string {
+  return `Welcome to ${Config.string('app.name')}`
+}
+```
+
+The route files are the exception: the app imports each one itself, afresh for every app and inside it, so a route
+file calls the `Route` facade at its top level.
+
+## Real-time facades
+
+Oriel has no real-time facades, which Laravel makes from any class you import with a `Facades\` namespace prefix.
+Make a facade for your class with `facade()`, as in [How facades work](#how-facades-work).
+
+## Facade class reference
+
+Every facade, and what it resolves. The bindings are the tokens of `@orieljs/framework/contracts`, which `inject()`
+and `app().make()` also take:
+
+| Facade | Resolves to | Binding |
+| --- | --- | --- |
+| `Artisan` | The console kernel: `call()` runs a command | `ConsoleKernel` |
+| `Auth` | The auth manager: `guard()`, and the default guard's `user()`, `check()`, `attempt()`… | `AuthFactory` |
+| `Bus` | The command bus: `dispatch()`, `chain()`, `batch()` | `BusDispatcher` |
+| `Cache` | The cache manager: `store()`, and the default store's methods | `CacheManager` |
+| `Config` | The configuration repository (see [The `Config` facade](#the-config-facade)) | `ConfigRepository` |
+| `Cookie` | The current request's cookie jar, plus `get()` and `has()` for the request's cookies | `CookieJar` (scoped) |
+| `Crypt` | The encrypter | `Encrypter` |
+| `DB` | The database manager: `connection()`, and the default connection's methods; `DB.raw()` | `DatabaseManager` |
+| `Event` | The event dispatcher | `EventDispatcher` |
+| `Gate` | The authorization gate | `Gate` |
+| `Hash` | The hash manager, which hashes with the default driver; `driver()` | `Hasher` |
+| `Inertia` | The current request's Inertia response factory | `InertiaFactory` (scoped) |
+| `Live` | The Live component manager: `Live.component()` registers a component; `Live.test()` mounts one in a test | `LiveManager` |
+| `Log` | The log manager: `channel()`, and the default channel's methods | `LogManager` |
+| `Mail` | The mail manager: `mailer()`, and the default mailer's methods | `MailManager` |
+| `Notification` | The notification dispatcher, through the statics of the `Notification` class | `NotificationDispatcher` |
+| `Password` | The default password broker; `broker()` | `PasswordBroker` |
+| `Queue` | The queue manager: `connection()`, and the default connection's methods | `QueueManager` |
+| `RateLimiter` | The rate limiter, which `throttle` uses: `hit()`, `tooManyAttempts()`, `clear()` | `RateLimiter` |
+| `Route` | The router | `Router` |
+| `Schedule` | The schedule: `command()`, `job()`, `call()` | `Schedule` |
+| `Schema` | The default database connection's schema builder | `SchemaBuilderToken`, from `@orieljs/framework` |
+| `Session` | The current request's session; `Session.extend()` | `Session` (scoped) |
+| `Storage` | The filesystem manager: `disk()`, and the default disk's methods | `FilesystemManager` |
+| `Validator` | The validation factory: `make()`, `extend()` | `ValidationFactory` |
+| `View` | The view factory: `make()`, `share()`, `composer()` | `ViewFactory` |
+
+A scoped facade needs a scope. Outside any, `Cookie` and `Session` throw a `BindingResolutionError` ("Scoped
+binding [Session.Store] was resolved outside a scope. …"), and `Inertia`, outside a request, uses the application's
+own response factory.
+
+`Inertia` and `Live` are written by hand rather than with `facade()`, and `Live` is also the `<Live>` element of your
+views. `Notification` is the base class of your notifications, whose statics are the facade (`NotificationFacade`,
+also exported, is a plain facade over the same dispatcher). None of the three has `getFacadeRoot()`, and only
+`Notification` has `swap()`.
+
+> [!NOTE]
+> Laravel's `App`, `Request`, `Response`, `Redirect`, `URL`, `Lang` and `Vite` facades are helpers in Oriel: `app()`,
+> `request()`, `response()`, `redirect()`, `url()`, `__()` and `vite()`. Oriel has no facade for Laravel's `Blade`,
+> `Broadcast`, `Context`, `Date`, `Exceptions`, `File`, `Http`, `Pipeline`, `Process` or `Redis`.
+
+### The `Config` facade
+
+`Config` resolves your app's configuration, as the `config()` helper does. It has the repository's `get()`, `set()`,
+`has()`, `push()` and `all()`, and adds `prepend()`, `getMany()` and typed getters:
+
+```ts
+const name = Config.string('app.name')
+
+const debug = Config.boolean('app.debug', false)
+
+const values = Config.getMany(['app.name', 'app.env'])
+```
+
+`string()`, `integer()`, `float()`, `boolean()` and `array()` return the value typed, or throw a `TypeError` when it
+isn't of that type: "Configuration value for key [app.name] must be a string, undefined given.". `float()` takes any
+number, and `array()` a list or an object. [Configuration](configuration.md) covers your configuration files.

package/docs/hashing.md

@@ -0,0 +1,118 @@
+# Hashing
+
+The `Hash` facade hashes your users' passwords with bcrypt or Argon2, and checks a password against its hash.
+
+## Introduction
+
+A password is stored as a hash, which can't be turned back into the password: to sign a user in, Oriel hashes what they
+typed and compares the two. Bcrypt, the default, is slow on purpose, and its work factor can rise as computers get
+faster, so guessing passwords from a stolen hash stays costly. The starter kits hash with bcrypt when users register,
+and check the hash when they sign in.
+
+## Configuration
+
+`config/hashing.ts` names the driver, `bcrypt` unless `HASH_DRIVER` names another, and each driver's settings:
+
+```ts title="config/hashing.ts"
+import { env } from '@orieljs/framework'
+
+export default {
+  driver: env('HASH_DRIVER', 'bcrypt'),
+  bcrypt: { rounds: Number(env('BCRYPT_ROUNDS', 12)), verify: true },
+  argon: { memory: 65536, threads: 1, time: 4, verify: true },
+  rehash_on_login: true,
+}
+```
+
+The drivers are `bcrypt`, `argon` (Argon2i) and `argon2id`. Bcrypt's `rounds` is its work factor; Argon2's `memory`
+(in KiB), `time` and `threads` are its. The settings may be numbers or the strings `env()` gives, such as `'12'`.
+
+Your tests run with `BCRYPT_ROUNDS=4`, so the hashing in them is quick.
+
+## Basic usage
+
+### Hashing passwords
+
+`Hash.make()` hashes a value with your driver. It returns a promise:
+
+```ts title="app/Http/Controllers/PasswordController.ts"
+import { Hash, redirect, request } from '@orieljs/framework'
+import type { User } from '../../Models/User'
+import { Controller } from './Controller'
+
+export class PasswordController extends Controller {
+  /** Update the password for the user. */
+  async update() {
+    // Validate the new password length...
+
+    const user = (await request().user<User>())!
+
+    await user.fill({ password: await Hash.make(request().string('newPassword').toString()) }).save()
+
+    return redirect('/profile')
+  }
+}
+```
+
+A model can do this for you: an attribute with the `hashed` cast is hashed when the model is saved, and a value that is
+already a hash made with your current settings is kept. [Hashed casting](eloquent-mutators.md#hashed-casting) describes
+it.
+
+#### Adjusting the work factor
+
+`Hash.make()` takes the value only. Set the work factor in `config/hashing.ts`, or, for bcrypt, pass it to the
+`bcrypt()` helper, which hashes with bcrypt whatever your driver is:
+
+```ts
+const hashed = await bcrypt('password', { rounds: 12 })
+```
+
+> [!NOTE]
+> Laravel's `Hash::make()` takes the work factor as a second argument. Oriel's `Hash.make()` reads it from your
+> config, and `bcrypt()` takes `rounds`.
+
+### Verifying that a password matches a hash
+
+`Hash.check()` hashes a password and compares it with a hash. It returns a promise too:
+
+```ts
+declare const hashedPassword: string
+// ---cut---
+if (await Hash.check('plain-text', hashedPassword)) {
+  // The passwords match...
+}
+```
+
+An empty hash never matches.
+
+### Determining if a password needs to be rehashed
+
+`Hash.needsRehash()` tells you whether a hash was made with other settings than your current ones, such as fewer
+rounds or another algorithm. It is synchronous:
+
+```ts
+declare let hashed: string
+// ---cut---
+if (Hash.needsRehash(hashed)) {
+  hashed = await Hash.make('plain-text')
+}
+```
+
+With `rehash_on_login` on, as in a new app, signing a user in with `Auth.attempt()` does this for you: when the
+password matches and its hash needs rehashing, the user's password is hashed again and saved.
+
+### Other methods
+
+- `Hash.info(hashed)` gives a hash's algorithm and options, such as `{ algorithm: 'bcrypt', options: { cost: 12 } }`.
+- `Hash.isHashed(value)` tells you whether a value is a bcrypt or Argon2 hash.
+- `Hash.driver('argon2id')` returns another driver, to hash or check with it.
+
+Bcrypt hashes start with `$2y$`, as PHP's `password_hash()` writes them, so the hashes of a Laravel app's users check
+in Oriel, and the other way round.
+
+## Hash algorithm verification
+
+With `verify` on, as in a new app, `Hash.check()` refuses a hash made by another algorithm than the driver's: it
+throws a `HashAlgorithmError`, "This password does not use the Bcrypt algorithm.", rather than return `false`. This
+stops a hash of another kind from being checked in a way it wasn't meant for. When you move your users from one
+algorithm to another, set `verify: false` in the driver's settings while their old hashes remain.