|
| 1 | +# conditional-request-middleware |
| 2 | + |
| 3 | +HTTP conditional request middleware. |
| 4 | + |
| 5 | +Compliant with |
| 6 | +[RFC 9110, 13. Conditional Requests](https://www.rfc-editor.org/rfc/rfc9110#section-13) |
| 7 | + |
| 8 | +[](https://deno.land/x/conditional_request_middleware) |
| 9 | +[](https://doc.deno.land/https/deno.land/x/conditional_request_middleware/mod.ts) |
| 10 | +[](https://github.com/httpland/conditional-request-middleware/releases) |
| 11 | +[](https://codecov.io/gh/httpland/conditional-request-middleware) |
| 12 | +[](https://github.com/httpland/conditional-request-middleware/blob/main/LICENSE) |
| 13 | + |
| 14 | +[](https://github.com/httpland/conditional-request-middleware/actions/workflows/test.yaml) |
| 15 | +[](https://nodei.co/npm/@httpland/conditional-request-middleware/) |
| 16 | + |
| 17 | +## Middleware |
| 18 | + |
| 19 | +For a definition of Universal HTTP middleware, see the |
| 20 | +[http-middleware](https://github.com/httpland/http-middleware) project. |
| 21 | + |
| 22 | +## Usage |
| 23 | + |
| 24 | +To evaluate precondition, you need to provide a function to retrieve the |
| 25 | +selected representation. |
| 26 | + |
| 27 | +The following example evaluates the `If-None-Match` precondition and controls |
| 28 | +the handler. |
| 29 | + |
| 30 | +```ts |
| 31 | +import { conditionalRequest } from "https://deno.land/x/conditional_request_middleware@$VERSION/mod.ts"; |
| 32 | +import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; |
| 33 | +import { assertSpyCalls, spy } from "https://deno.land/std/testing/mock.ts"; |
| 34 | + |
| 35 | +const selectedRepresentation = new Response("<body>", { |
| 36 | + headers: { etag: "<etag>" }, |
| 37 | +}); |
| 38 | +const selectRepresentation = spy(() => selectedRepresentation); |
| 39 | +const middleware = conditionalRequest(selectRepresentation); |
| 40 | +const request = new Request("<uri>", { |
| 41 | + headers: { "if-none-match": "<etag>" }, |
| 42 | +}); |
| 43 | +const handler = spy(() => selectedRepresentation); |
| 44 | + |
| 45 | +const response = await middleware(request, handler); |
| 46 | + |
| 47 | +assertSpyCalls(handler, 0); |
| 48 | +assertSpyCalls(selectRepresentation, 1); |
| 49 | +assertEquals(response.status, 304); |
| 50 | +``` |
| 51 | + |
| 52 | +## Preconditions |
| 53 | + |
| 54 | +[RFC 9110, 13.1. Preconditions](https://www.rfc-editor.org/rfc/rfc9110#section-13.1) |
| 55 | +compliant and supports the following precondition: |
| 56 | + |
| 57 | +- If-Match |
| 58 | +- If-None-Match |
| 59 | +- If-Modified-Since |
| 60 | +- If-Unmodified-Since |
| 61 | +- If-Range |
| 62 | + |
| 63 | +If multiple precondition headers are present, precondition is processed |
| 64 | +according to |
| 65 | +[precedence](https://www.rfc-editor.org/rfc/rfc9110.html#section-13.2.2). |
| 66 | + |
| 67 | +## Effects |
| 68 | + |
| 69 | +Middleware will effect following: |
| 70 | + |
| 71 | +- HTTP response status |
| 72 | + - [304 (Not Modified)](https://www.rfc-editor.org/rfc/rfc9110#section-15.4.5) |
| 73 | + - [412 (Precondition Failed)](https://www.rfc-editor.org/rfc/rfc9110#section-15.5.13) |
| 74 | + |
| 75 | +## Conditions |
| 76 | + |
| 77 | +Middleware will execute only if the following conditions are met: |
| 78 | + |
| 79 | +- The precondition header exists |
| 80 | + - `If-Match` |
| 81 | + - The `ETag` header exist |
| 82 | + - `If-None-Match` |
| 83 | + - The `ETag` header exist |
| 84 | + - `If-Modified-Since` |
| 85 | + - The `Last-Modified` header exist |
| 86 | + - `If-Unmodified-Since` |
| 87 | + - The `Last-Modified` header exist |
| 88 | + |
| 89 | +## License |
| 90 | + |
| 91 | +Copyright © 2023-present [httpland](https://github.com/httpland). |
| 92 | + |
| 93 | +Released under the [MIT](./LICENSE) license |
0 commit comments