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

package/docs/requests.md

@@ -0,0 +1,533 @@
+# HTTP requests
+
+The `request()` helper gives you the current HTTP request: its URL, headers and input, the files it uploaded and the
+cookies it sent.
+
+## Interacting with the request
+
+### Accessing the request
+
+Call `request()` anywhere in your code while a request is handled: in a route, a controller, a middleware or a view.
+It returns the same object each time for the same 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().input<string>('name')
+
+    // Store the user...
+
+    return redirect('/users')
+  }
+}
+```
+
+The same goes for a route's closure:
+
+```ts
+Route.get('/', () => {
+  const page = request().query('page', '1')
+
+  return `Page ${page}`
+})
+```
+
+`request('name')` is a short form of `request().input('name')`, and takes a default too.
+
+> [!NOTE]
+> Laravel injects the request into a closure or a controller method that type-hints it. TypeScript types are gone
+> when your app runs, so Oriel can't see them: an action receives its route parameters and nothing else, and reads the
+> request from `request()`.
+
+#### Route parameters
+
+A route's parameters are still the action's arguments, in the order of the URI:
+
+```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().input<string>('name') })
+
+    return redirect('/users')
+  }
+}
+```
+
+`request().route('id')` reads one of them from anywhere else, after [model binding](routing.md#route-model-binding),
+and `request().route()` gives them all.
+
+### Request path, host, and method
+
+#### Retrieving the request path
+
+`path()` returns the request's path without the slashes at its ends. For `http://example.com/foo/bar`, it is
+`foo/bar`; for the home page, `/`:
+
+```ts
+const uri = request().path()
+```
+
+#### Inspecting the request path and route
+
+`is()` checks the path against one or more patterns, where `*` matches anything:
+
+```ts
+if (request().is('admin/*')) {
+  // ...
+}
+```
+
+`routeIs()` checks the name of the route the request matched, the same way:
+
+```ts
+if (request().routeIs('admin.*')) {
+  // ...
+}
+```
+
+#### Retrieving the request URL
+
+`url()` returns the URL without its query string, and `fullUrl()` with it:
+
+```ts
+const url = request().url()
+
+const urlWithQueryString = request().fullUrl()
+```
+
+#### Retrieving the request host
+
+`root()` returns the scheme and the host, as `https://example.com`, and `secure()` tells you whether the request came
+over HTTPS. Behind a proxy, both follow the proxy's `X-Forwarded-*` headers once you
+[trust it](#configuring-trusted-proxies).
+
+#### Retrieving the request method
+
+`method()` returns the request's verb, upper-cased, and `isMethod()` compares it in any case:
+
+```ts
+const method = request().method()
+
+if (request().isMethod('post')) {
+  // ...
+}
+```
+
+A form's `_method` field, or an `X-HTTP-Method-Override` header, changes the method of a `POST`: see
+[form method spoofing](routing.md#form-method-spoofing).
+
+### Request headers
+
+`header()` returns a header, by its name in any case, or `undefined` when the request doesn't have it. A second
+argument is the default:
+
+```ts
+const value = request().header('X-Header-Name')
+
+const withDefault = request().header('X-Header-Name', 'default')
+```
+
+`bearerToken()` returns the token of an `Authorization: Bearer` header, or `undefined`, and `userAgent()` the
+`User-Agent` header:
+
+```ts
+const token = request().bearerToken()
+```
+
+### Request IP address
+
+`ip()` returns the address of the client that sent the request, or `undefined` when the server doesn't know it:
+
+```ts
+const ipAddress = request().ip()
+```
+
+Behind a [trusted proxy](#configuring-trusted-proxies), it is the client's address from `X-Forwarded-For`. Treat an
+IP address as information the client controls.
+
+### Content negotiation
+
+`expectsJson()` tells you whether the request wants a JSON response: its `Accept` header asks for JSON first, or it
+is an AJAX request that accepts anything. `wantsJson()` checks the `Accept` header alone, and `ajax()` the
+`X-Requested-With: XMLHttpRequest` header:
+
+```ts
+if (request().expectsJson()) {
+  // ...
+}
+```
+
+The exception handler uses `expectsJson()` to choose between an HTML error page and JSON: see
+[Error handling](errors.md).
+
+### The web-standard request
+
+`request().raw` is the web-standard `Request` the server received. Oriel reads JSON, URL-encoded and multipart bodies
+for you; a body of any other type is left unread, so read it from `raw`:
+
+```ts
+Route.post('/hooks/raw', async () => {
+  const bytes = await request().raw.arrayBuffer()
+
+  return { received: bytes.byteLength }
+})
+```
+
+> [!WARNING]
+> A body you read from `raw` isn't held to the size limit of the bodies Oriel reads (see
+> [body size limits](#body-size-limits)): check its size yourself.
+
+## Input
+
+### Retrieving input
+
+#### Retrieving all input data
+
+`all()` returns the request's input, from the query string and the body, with its uploaded files:
+
+```ts
+const input = request().all()
+```
+
+#### Retrieving an input value
+
+`input()` returns one value, whatever the request's verb, from the body or, when the body hasn't the key, from the
+query string. A second argument is the default when the key is missing:
+
+```ts
+const name = request().input('name')
+
+const withDefault = request().input('name', 'Sally')
+```
+
+Form fields named with brackets, such as `products[0][name]`, arrive nested. Reach into them with dots:
+
+```ts
+const name = request().input('products.0.name')
+```
+
+`input()` with no key returns every value, without the files.
+
+`input()` returns `unknown` unless you give it a type, as in `input<string>('name')`. That type is a cast, not a
+check: the client can send anything, so [validate](validation.md) the input you rely on.
+
+#### Retrieving input from the query string
+
+`query()` reads the query string only, with the same defaults, and with no key returns it all:
+
+```ts
+const name = request().query('name')
+
+const withDefault = request().query('name', 'Helen')
+
+const query = request().query()
+```
+
+#### Retrieving JSON input values
+
+A request with a JSON body, sent with a `Content-Type` of `application/json` (or any type that ends in `+json`), has
+the JSON as its input, so `input()` reads it with dots too:
+
+```ts
+const name = request().input('user.name')
+```
+
+`content()` returns the raw text of a JSON or URL-encoded body. A body that isn't valid JSON reads as empty input.
+
+#### Retrieving stringable input values
+
+`string()` returns a value as a [`Stringable`](helpers.md#fluent-strings), so you can chain string methods onto it. A
+missing value is the empty string, or the default you give:
+
+```ts
+const name = request().string('name').trim().toString()
+```
+
+`str()` is the same method under a shorter name.
+
+#### Retrieving integer input values
+
+`integer()` reads a value as a whole number, from its leading digits, as PHP's `intval` does. A missing value gives
+the default (`0` unless you give one), and text that doesn't start with a number gives `0`:
+
+```ts
+const perPage = request().integer('per_page', 15)
+```
+
+#### Retrieving boolean input values
+
+Checkboxes and other fields send truthy text, such as `on`. `boolean()` returns `true` for `1`, `'1'`, `true`,
+`'true'`, `'on'` and `'yes'`, in any case, and `false` for everything else. A missing value gives the default
+(`false` unless you give one):
+
+```ts
+const archived = request().boolean('archived')
+```
+
+#### Retrieving a portion of the input data
+
+`only()` and `except()` take a list of keys, or the keys as arguments, and accept dots:
+
+```ts
+const credentials = request().only(['username', 'password'])
+
+const sameCredentials = request().only('username', 'password')
+
+const withoutCard = request().except(['credit_card'])
+
+const withoutCardEither = request().except('credit_card')
+```
+
+> [!WARNING]
+> `only()` returns the keys that are present: a key the request didn't send isn't in its result, not even as
+> `undefined`.
+
+### Input presence
+
+`has()` tells you whether every key you give is present, even with an empty value, and `hasAny()` whether one of them
+is:
+
+```ts
+if (request().has('name')) {
+  // ...
+}
+
+if (request().has(['name', 'email'])) {
+  // ...
+}
+
+if (request().hasAny(['name', 'email'])) {
+  // ...
+}
+```
+
+`filled()` tells you whether a value is present and not blank: not `null`, not text made only of spaces, not an empty
+list or object. `missing()` is the opposite of `has()`:
+
+```ts
+if (request().filled('name')) {
+  // ...
+}
+
+if (request().missing('name')) {
+  // ...
+}
+```
+
+### Merging additional input
+
+`merge()` adds values to the request's input, replacing those it already has:
+
+```ts
+request().merge({ votes: 0 })
+```
+
+### Old input
+
+Oriel can keep a request's input for the next request, so a form can show what the user typed after a failed
+validation. When validation fails, Oriel does this for you, and leaves out the password fields.
+
+#### Flashing input then redirecting
+
+`withInput()` on a redirect flashes the input to the session. It takes the input to flash, or flashes all of it:
+
+```ts
+const back = redirect('/form').withInput()
+
+const toRoute = redirect().route('user.create').withInput()
+
+const withoutPassword = redirect('/form').withInput(request().except('password'))
+```
+
+#### Retrieving old input
+
+`old()` returns a value the previous request flashed, or the default you give. In a TSX view, it fills a field
+again:
+
+```tsx title="resources/views/user/create.tsx"
+import { csrfField, old } from '@orieljs/framework'
+
+export default function Create() {
+  return (
+    <form method="post" action="/users">
+      {csrfField()}
+      <input type="text" name="username" value={old('username', '')} />
+      <button type="submit">Create</button>
+    </form>
+  )
+}
+```
+
+`old()` works in the rest of your code too, as does `request().session().getOldInput('username')`. Laravel's
+`$request->flash()`, `flashOnly()` and `flashExcept()` aren't on Oriel's request: flash input with `withInput()`, or
+with the session's `flashInput()`.
+
+### Cookies
+
+#### Retrieving cookies from requests
+
+The cookies Oriel sets are encrypted, and a cookie that doesn't decrypt is dropped, so the client can't change one.
+`cookie()` returns a cookie's decrypted value, or `undefined`:
+
+```ts
+const value = request().cookie('name')
+```
+
+`Cookie.get('name')` reads the same value through the `Cookie` [facade](facades.md), and `request().cookies()` returns
+them all. [Responses](responses.md) covers setting cookies.
+
+Cookies are decrypted by the `web` middleware group: in `routes/api.ts`, `cookie()` returns them as the client sent
+them.
+
+A cookie your scripts write isn't encrypted, so `EncryptCookies` drops it as one that doesn't decrypt. List its name
+with `EncryptCookies.except('appearance')` in `bootstrap/app.ts` to read it as it is, as the starter kits do.
+
+## Input trimming and normalization
+
+Two global middleware tidy the input of every request before your code sees it, as in Laravel: `TrimStrings` trims
+every text value, except the `password`, `password_confirmation` and `current_password` fields, and
+`ConvertEmptyStringsToNull` turns empty text into `null`. They apply to the query string and to the body, JSON
+included. They always run: Laravel's switches to turn them off, for every request or some, aren't in Oriel.
+
+## Files
+
+### Retrieving uploaded files
+
+`file()` returns an uploaded file from a multipart form, or `undefined`, and `hasFile()` tells you whether there is
+one. A file field left empty doesn't count:
+
+```ts
+const file = request().file('photo')
+
+if (request().hasFile('photo')) {
+  // ...
+}
+```
+
+`allFiles()` returns every uploaded file, by field name.
+
+#### File names and extensions
+
+An uploaded file has the name, the MIME type and the size the browser gave it, in `clientName`, `mimeType` and
+`size`. `extension()` guesses the extension from the file's content, so it can differ from the one in its name, which
+`clientExtension()` returns:
+
+```ts
+declare const file: UploadedFile
+// ---cut---
+const extension = file.extension() // 'png', from the bytes
+const clientExtension = file.clientExtension() // 'jpg', from photo.jpg
+```
+
+`extension()` reads the first bytes of the file. When they show a known format, its extension wins. Otherwise the
+client's claim is kept, unless it names a format the bytes would have shown, or a type a browser renders or runs,
+such as `html` or `svg`; then plain text is `txt`, and anything else has no extension.
+
+#### Other file methods
+
+`hashName()` returns a random 40-character name with that extension, of the kind `store()` gives the file, and a new
+one each time you call it. `arrayBuffer()`, `text()` and `stream()` read the file's content:
+
+```ts
+declare const file: UploadedFile
+// ---cut---
+const name = file.hashName() // 'Xb3bTx...Q9.png'
+const text = await file.text()
+const stream = file.stream()
+```
+
+### Storing uploaded files
+
+`store()` saves an uploaded file on one of your filesystem disks, in the folder you name, under a new random name of the
+kind `hashName()` makes. It returns the file's path on the disk, such as `images/<name>.png`. A second argument names
+the disk; without it, the default disk is used:
+
+```ts
+declare const file: UploadedFile
+// ---cut---
+const path = await file.store('images')
+
+const onS3 = await file.store('images', 's3')
+```
+
+`storeAs()` takes the file's name as well:
+
+```ts
+declare const file: UploadedFile
+// ---cut---
+const path = await file.storeAs('images', 'filename.jpg')
+
+const onS3 = await file.storeAs('images', 'filename.jpg', 's3')
+```
+
+Disks are configured in `config/filesystems.ts`; [File storage](storage.md) covers them.
+
+> [!NOTE]
+> Laravel's uploaded files have `isValid()`, which checks that the upload succeeded, and `path()`, the path of the
+> temporary file PHP wrote. Oriel's have neither: an upload is read into memory with the rest of the body, so a file
+> `file()` returns has arrived whole, and has no path until you store it.
+
+## Body size limits
+
+Oriel reads a JSON, URL-encoded or multipart body into memory before your code runs, and refuses a body larger than
+`http.max_body_size`: 8 MB unless you change it. A larger body gets a 413 ("Content Too Large"), and when the
+`Content-Length` header gives the size, the body isn't read at all. The limit is the same for every route.
+
+A JSON body can also nest objects and arrays only so deep: past `http.max_json_depth`, 512 levels unless you change
+it, the request gets a 400 ("The request body is nested too deeply.").
+
+Raise them in `config/http.ts`, where `max_body_size` is a number of bytes, and `null` turns either limit off:
+
+```ts title="config/http.ts"
+export default {
+  trusted_proxies: [],
+  csrf_except: [],
+  redirect_guests_to: '/login',
+  max_body_size: 20 * 1024 * 1024,
+  max_json_depth: 512,
+}
+```
+
+> [!WARNING]
+> The limit counts the whole body, files included. To accept uploads larger than 8 MB, such as the 12 MB
+> [Live's uploads](live.md#file-uploads) allow, raise `max_body_size` above the largest you accept.
+
+## Configuring trusted proxies
+
+Behind a load balancer or a proxy that ends TLS, your app sees the proxy's request, over HTTP, from the proxy's
+address. Tell Oriel which proxies to trust with `trusted_proxies` in `config/http.ts`: exact addresses, IPv4 ranges
+such as `10.0.0.0/8`, or `*` for any:
+
+```ts title="config/http.ts"
+export default {
+  trusted_proxies: ['192.168.1.1', '10.0.0.0/8'],
+  csrf_except: [],
+  redirect_guests_to: '/login',
+  max_body_size: 8 * 1024 * 1024,
+}
+```
+
+For a request from a trusted proxy, `ip()` reads the client's address from `X-Forwarded-For`, and the scheme and
+host come from `X-Forwarded-Proto` and `X-Forwarded-Host`, so `url()`, `route()` and `secure()` match what the
+browser asked for. The list may also be a comma-separated string, so it can come from your `.env`:
+`trusted_proxies: env('TRUSTED_PROXIES', '')`.
+
+#### Trusting all proxies
+
+When you can't know your load balancers' addresses, as with many cloud providers, trust them all with `'*'`. Do it
+only when nothing can reach your app except through them: any client could then set the `X-Forwarded-*` headers.
+
+Laravel's trusted hosts (`trustHosts()`) aren't in Oriel: let your web server or load balancer refuse unknown hosts.