@alxia/create 0.5.14 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -36,8 +36,8 @@ bun create @alxia my-site --template react-router
36
36
  | template | what it writes |
37
37
  | --- | --- |
38
38
  | `minimal` | the smallest alxia app: `src/index.ts` exports `app = alxia().get("/", …)` and listens on `PORT` only when it is the entry file, `src/index.spec.ts` calls it with `app.request()`; `bun dev` (`NODE_ENV=development bun --hot`), `build`, `start`, `typecheck`, a strict `tsconfig.json`, Biome and `verify` (`check:ci`, `typecheck`, then `test`), a `Dockerfile` running on `oven/bun:1-alpine`, `.dockerignore`, `.gitignore`, `.vscode/` and a README. One dependency, `@alxia/core`: no OpenAPI, no code generation, no validator, no env file |
39
- | `api` | an `@alxia/core` app with Zod, OpenAPI spec first: `openapi.yaml` declares `GET /todos`, `POST /todos` and `GET /todos/{id}`; `bun run generate` writes `src/generated/` from it with [`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen) (`openapi-codegen.config.ts`), committed, so nothing is generated at install or build; `src/env.ts` reads `PORT`, `API_KEY`, `API_DOCS` and an optional `TRUSTED_PROXIES` (CIDR ranges, which adds `trustProxy({ trusted, untrusted: "refuse" })` to the base when set: `ctx.ip` from a trusted proxy's `X-Forwarded-For`, a forwarding header from any other connection refused, health probes untouched) with `defineEnv` from [`@alxia/env`](https://www.npmjs.com/package/@alxia/env), `API_KEY` a secret defaulting to `dev-key` under `NODE_ENV` `development` and `test` alone, required anywhere else; `src/context.ts` holds the base the routes read, `alxia({ errors: "problem" })` so alxia's own errors are RFC 9457 problems as `openapi.yaml` declares them, and registers it with `@alxia/core`'s `Register`; `src/routes/todos.ts`, made with `defineRoutes()`, reads that context with no import of the app and binds each operation with `route(operation, …middlewares, handler)`, as `route(operations.createTodo, requireKey, handler)`, where `requireKey`, made with `defineMiddleware`, answers 401 without an API key, and the operation's schemas validate the request and check the handler's reply; `src/app.ts` mounts `health()` (`GET /health`, `GET /ready`), `apiDocs` from `@alxia/openapi` (the API reference at `/docs`, from `openapi.yaml` imported into the bundle; on in development, else with `API_DOCS=true`) and the routes on the base; a `bun test` spec, `src/proxy.spec.ts`, building the base behind `TRUSTED_PROXIES` and calling `app.fetch` with a peer, `src/env.spec.ts`, checking that a malformed `TRUSTED_PROXIES` stops the app, and a `bun test` spec calling the app through the typed [`@nxgt/openapi-httpyz`](https://www.npmjs.com/package/@nxgt/openapi-httpyz) client over the generated `operations.ts`, its `fetch` being `app.fetch` (in process, no server; replies narrowed on their status), keeping one `app.request()` test, and asserting `matchesSpec` from [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi): every operation has its route, and `strict: true` also fails on a route outside the spec; `bun dev` (`NODE_ENV=development`) restarting on change, `typecheck`, `build`, a strict `tsconfig.json`, Biome (`biome.json`, `lint`, `format`, `check`, `check:ci`), `verify`, starting with `generate --check`, a `Dockerfile` running on `oven/bun:1-alpine`, `.dockerignore`, `.gitignore`, `.env.example`, `.vscode/` and a README. `@alxia/openapi` is a dependency; `@nxgt/httpyz`, `@nxgt/openapi-httpyz` and `@nxgt/openapi-codegen` are devDependencies |
40
- | `graphql` | a GraphQL API with [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) through [`@alxia/graphql`](https://www.npmjs.com/package/@alxia/graphql), schema first: `schema.graphql` is the contract (`Query`, `Mutation`, `Subscription`); `bun run generate` writes `src/generated/resolvers.ts` from it with [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) (`codegen.ts`), committed, typing `Resolvers` with the app's context; `src/context.ts` holds the base and `viewerOf`, a middleware reading `Authorization: Bearer <token>` so every resolver reads a typed `viewer`; `src/loaders.ts`, `createLoaders()`, the [DataLoader](https://github.com/graphql/dataloader)s of one request, built per request by the `context` option of `graphql()` in `src/app.ts` so `Note.author` loads the authors of a list of notes in one batch (`findUsers`) instead of one call per note; `src/resolvers.ts`; `src/schema.ts` and `src/app.ts` mounting `health()` and `graphql(app, { schema, context })`, GraphiQL on in dev alone; `src/env.ts` (`PORT` and the optional `TRUSTED_PROXIES`, as `api`) with `defineEnv`; `src/store.ts`, in memory, with the pub/sub of the `noteAdded` subscription (server-sent events); a `bun test` spec posting to `/graphql` through `app.request()`, `src/proxy.spec.ts`, the base behind `TRUSTED_PROXIES`, and `src/env.spec.ts`, a malformed one refused; the same scripts, `Dockerfile`, Biome and `.vscode/` as `api`, `verify` starting with `generate --check`, and a `.env.example`. `@alxia/graphql`, `@alxia/env`, `dataloader`, `graphql` and `graphql-yoga` are dependencies; the code generator is a devDependency |
39
+ | `api` | an `@alxia/core` app with Zod, OpenAPI spec first: `openapi.yaml` declares `GET /todos`, `POST /todos` and `GET /todos/{id}`; `bun run generate` writes `src/generated/` from it with [`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen) (`openapi-codegen.config.ts`), committed, so nothing is generated at install or build; `src/env.ts` reads `PORT`, `API_KEY`, `API_DOCS` and an optional `TRUSTED_PROXIES` (CIDR ranges, which adds `trustProxy({ trusted, untrusted: "refuse" })` to the base when set: `ctx.ip` from a trusted proxy's `X-Forwarded-For`, a forwarding header from any other connection refused, health probes untouched) with `defineEnv` from [`@alxia/env`](https://www.npmjs.com/package/@alxia/env), `API_KEY` a secret defaulting to `dev-key` under `NODE_ENV` `development` and `test` alone, required anywhere else; `src/context.ts` holds the base the routes read, `alxia({ errors: "problem" })` so alxia's own errors are RFC 9457 problems as `openapi.yaml` declares them, and registers it with `@alxia/core`'s `Register`; `src/routes/todos.ts`, made with `defineRoutes()`, reads that context with no import of the app and binds each operation with `route(operation, …middlewares, handler)`, as `route(operations.createTodo, requireKey, handler)`, where `requireKey`, made with `defineMiddleware`, answers 401 without an API key, and the operation's schemas validate the request and check the handler's reply; `src/app.ts` mounts `health()` (`GET /health`, `GET /ready`), `apiDocs` from `@alxia/openapi` (the API reference at `/docs`, from `openapi.yaml` imported into the bundle; on in development, else with `API_DOCS=true`) and the routes on the base; a `bun test` spec, `src/proxy.spec.ts`, building the base behind `TRUSTED_PROXIES` and calling `app.fetch` with a peer, `src/env.spec.ts`, checking that a malformed `TRUSTED_PROXIES` stops the app (the keyword `cloudflare` expands to Cloudflare's ranges), and a `bun test` spec calling the app through the typed [`@nxgt/openapi-httpyz`](https://www.npmjs.com/package/@nxgt/openapi-httpyz) client over the generated `operations.ts`, its `fetch` being `app.fetch` (in process, no server; replies narrowed on their status), keeping one `app.request()` test, and asserting `matchesSpec` from [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi): every operation has its route, and `strict: true` also fails on a route outside the spec; `bun dev` (`NODE_ENV=development`) restarting on change, `typecheck`, `build`, a strict `tsconfig.json`, Biome (`biome.json`, `lint`, `format`, `check`, `check:ci`), `verify`, starting with `generate --check`, a `Dockerfile` running on `oven/bun:1-alpine`, `.dockerignore`, `.gitignore`, `.env.example`, `.vscode/` and a README. `@alxia/openapi` is a dependency; `@nxgt/httpyz`, `@nxgt/openapi-httpyz` and `@nxgt/openapi-codegen` are devDependencies |
40
+ | `graphql` | a GraphQL API with [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) through [`@alxia/graphql`](https://www.npmjs.com/package/@alxia/graphql), schema first: `schema.graphql` is the contract (`Query`, `Mutation`, `Subscription`); `bun run generate` writes `src/generated/resolvers.ts` from it with [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) (`codegen.ts`), committed, typing `Resolvers` with the app's context; `src/context.ts` holds the base and `viewerOf`, a middleware reading `Authorization: Bearer <token>` so every resolver reads a typed `viewer`; `src/loaders.ts`, `createLoaders()`, the [DataLoader](https://github.com/graphql/dataloader)s of one request, built per request by the `context` option of `graphql()` in `src/app.ts` so `Note.author` loads the authors of a list of notes in one batch (`findUsers`) instead of one call per note; `src/resolvers.ts`; `src/schema.ts` and `src/app.ts` mounting `health()` and `graphql(app, { schema, context })`, GraphiQL on in dev alone; `src/env.ts` (`PORT` and the optional `TRUSTED_PROXIES`, as `api`) with `defineEnv`; `src/store.ts`, in memory, with the pub/sub of the `noteAdded` subscription (server-sent events); a `bun test` spec posting to `/graphql` through `app.request()`, `src/proxy.spec.ts`, the base behind `TRUSTED_PROXIES`, and `src/env.spec.ts`, a malformed one refused (the keyword `cloudflare` is accepted); the same scripts, `Dockerfile`, Biome and `.vscode/` as `api`, `verify` starting with `generate --check`, and a `.env.example`. `@alxia/graphql`, `@alxia/env`, `dataloader`, `graphql` and `graphql-yoga` are dependencies; the code generator is a devDependency |
41
41
  | `react-router` | React Router's official template, as `create-react-router` writes it, shipped in this package and copied, with [`@alxia/react-router`](https://www.npmjs.com/package/@alxia/react-router) added as its README says: `alxia()` in `vite.config.ts`'s plugins, `dev` under `NODE_ENV=development`, `start` running `NODE_ENV=production bun build/server/index.js`, a `bunfig.toml` starting React Router's CLI on Bun, a `Dockerfile` running on `oven/bun:1-alpine` in place of React Router's Node one, and Biome as the `api` project has it, the scaffold formatted by it once. No server file: the default one serves the pages; `bunx alxia-react-router reveal` writes it out to customise |
42
42
 
43
43
  The heart of the `api` project, its middleware and a route bound to an
package/docs/guide.md CHANGED
@@ -335,7 +335,7 @@ instead:
335
335
  ### `src/env.ts`
336
336
 
337
337
  ```ts
338
- import { trustProxy } from "@alxia/core";
338
+ import { parseTrustedProxies } from "@alxia/core";
339
339
  import { defineEnv } from "@alxia/env";
340
340
  import { z } from "zod";
341
341
 
@@ -343,16 +343,6 @@ import { z } from "zod";
343
343
  // production included, is a deployment.
344
344
  const local = ["development", "test"].includes(Bun.env.NODE_ENV ?? "");
345
345
 
346
- // A range or an address trustProxy accepts: it throws on any other.
347
- const isRange = (range: string) => {
348
- try {
349
- trustProxy({ trusted: [range], untrusted: "refuse" });
350
- return true;
351
- } catch {
352
- return false;
353
- }
354
- };
355
-
356
346
  export const env = defineEnv(
357
347
  {
358
348
  PORT: z.coerce.number().default(3000),
@@ -360,14 +350,19 @@ export const env = defineEnv(
360
350
  API_DOCS: z.stringbool().default(Bun.env.NODE_ENV === "development"),
361
351
  TRUSTED_PROXIES: z
362
352
  .string()
363
- .transform((list) =>
364
- list
365
- .split(",")
366
- .map((range) => range.trim())
367
- .filter(Boolean),
368
- )
369
- .pipe(z.array(z.string().refine(isRange, "not a CIDR range or address")))
370
- .transform((ranges) => (ranges.length > 0 ? ranges : undefined))
353
+ .transform((list, ctx) => {
354
+ try {
355
+ const ranges = parseTrustedProxies(list);
356
+ return ranges.length > 0 ? ranges : undefined;
357
+ } catch (error) {
358
+ ctx.issues.push({
359
+ code: "custom",
360
+ message: (error as Error).message,
361
+ input: list,
362
+ });
363
+ return z.NEVER;
364
+ }
365
+ })
371
366
  .optional(),
372
367
  },
373
368
  { secret: ["API_KEY"] },
@@ -1078,6 +1073,17 @@ the base only when it is set:
1078
1073
  TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12 bun start
1079
1074
  ```
1080
1075
 
1076
+ Entries are validated by `@alxia/core`'s `parseTrustedProxies`: the keyword `cloudflare` is case-insensitive, an empty entry (`a,,b`), an entry with a port and a range that trusts every address (`0.0.0.0/0`) stop the app, and unset or blank declares no proxy.
1077
+
1078
+ Behind Cloudflare and a reverse proxy, the keyword `cloudflare` stands for
1079
+ Cloudflare's published ranges (`cloudflareRanges` of `@alxia/core`), beside
1080
+ your own proxy's network
1081
+ ([why every hop is listed](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/serving.md#behind-cloudflare-and-a-reverse-proxy)):
1082
+
1083
+ ```sh
1084
+ TRUSTED_PROXIES=cloudflare,172.16.0.0/12 bun start
1085
+ ```
1086
+
1081
1087
  - **From a trusted proxy**, `X-Forwarded-For` sets `ctx.ip`, read from the
1082
1088
  right, and `X-Forwarded-Proto` and `X-Forwarded-Host` give
1083
1089
  `originalUrl(ctx)`.
package/docs/roadmap.md CHANGED
@@ -7,7 +7,7 @@ number on it. Every release, with each change it made, is in
7
7
 
8
8
  ## Now
9
9
 
10
- Nothing in progress.
10
+ - **`TRUSTED_PROXIES=cloudflare`.** The `api` and `graphql` templates read the variable with `@alxia/core`'s `parseTrustedProxies`: the keyword `cloudflare` (any case) expands to Cloudflare's ranges, beside CIDR entries, and an empty entry stops the app.
11
11
 
12
12
  ## Next
13
13
 
@@ -730,11 +730,16 @@ later. A secret's value is never printed: `API_KEY` shows as `***`.
730
730
  PORT=3000 bun dev
731
731
  ```
732
732
 
733
- A malformed `TRUSTED_PROXIES` stops the app the same way, with
734
- `TRUSTED_PROXIES.1: not a CIDR range or address`, the number being the
735
- position of the bad entry, from 0: it is comma-separated CIDR
736
- ranges or addresses (`10.0.0.0/8,172.16.0.0/12`), and unset or empty it
737
- declares no proxy.
733
+ A malformed `TRUSTED_PROXIES` stops the app the same way, through
734
+ `@alxia/core`'s `parseTrustedProxies`, naming the entry. It is
735
+ comma-separated CIDR ranges or addresses (`10.0.0.0/8,172.16.0.0/12`) or the
736
+ keyword `cloudflare` (any case); unset or blank it declares no proxy:
737
+
738
+ - `TRUSTED_PROXIES: parseTrustedProxies: "not-a-range" is not an IP address, a CIDR range or the keyword cloudflare`
739
+ - `TRUSTED_PROXIES: parseTrustedProxies: entry 2 is empty`, for `a,,b` or a trailing comma (the entries count from 1)
740
+ - `TRUSTED_PROXIES: parseTrustedProxies: "10.0.0.1:8080" has a port: name the proxy's address or range alone`
741
+ - `TRUSTED_PROXIES: parseTrustedProxies: "10.0.0.0 /8" contains a space`
742
+ - `TRUSTED_PROXIES: parseTrustedProxies: "0.0.0.0/0" would trust every address`, also `::/0` and `::ffff:0:0/96`
738
743
 
739
744
  A variable the schema gives a default (`PORT`, the `api` project's
740
745
  `API_DOCS`) is fine unset. The `api` project's `API_KEY` defaults to
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alxia/create",
3
- "version": "0.5.14",
3
+ "version": "0.7.0",
4
4
  "description": "Start an alxia app: `bun create @alxia` writes a minimal API, a spec-first one, a GraphQL one, or React Router's official template served by alxia",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -41,11 +41,11 @@
41
41
  ]
42
42
  },
43
43
  "devDependencies": {
44
- "@alxia/core": "^0.18.1",
45
- "@alxia/env": "^0.3.1",
46
- "@alxia/graphql": "^0.13.2",
47
- "@alxia/openapi": "^0.6.13",
48
- "@alxia/react-router": "^0.36.0",
44
+ "@alxia/core": "^0.21.0",
45
+ "@alxia/env": "^0.5.0",
46
+ "@alxia/graphql": "^0.15.1",
47
+ "@alxia/openapi": "^0.6.16",
48
+ "@alxia/react-router": "^0.58.1",
49
49
  "@graphql-codegen/cli": "7.4.3",
50
50
  "@graphql-codegen/typescript": "6.1.0",
51
51
  "@graphql-codegen/typescript-resolvers": "6.1.0",
@@ -13,4 +13,6 @@ PORT=3000
13
13
  # comma-separated CIDR ranges or addresses, optional, unset by default: the proxies in front of
14
14
  # the app, a load balancer's. Set, X-Forwarded-For from one of them sets ctx.ip, and a forwarding
15
15
  # header from any other connection is refused with a 403. Unset, no forwarding header is read.
16
+ # Behind Cloudflare, the keyword `cloudflare` stands for its published ranges:
17
+ # TRUSTED_PROXIES=cloudflare,172.16.0.0/12
16
18
  # TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
@@ -9,6 +9,8 @@ const todos: Todo[] = [];
9
9
  // alxia's own errors — a 400 the schemas refuse, a 404 no route matches, a
10
10
  // 500 — are RFC 9457 problems, as openapi.yaml declares them.
11
11
  //
12
+ // Behind Cloudflare: TRUSTED_PROXIES=cloudflare,172.16.0.0/12 (`cloudflare` is
13
+ // its published ranges, then your own proxy's).
12
14
  // Behind a load balancer, set TRUSTED_PROXIES to its range: its
13
15
  // X-Forwarded-For then sets ctx.ip, and a forwarding header from any other
14
16
  // connection is refused with a 403. A request that carries none, a health
@@ -19,7 +19,7 @@ const load = async (trustedProxies: string) => {
19
19
 
20
20
  test("a malformed TRUSTED_PROXIES stops the app, naming the variable", async () => {
21
21
  await expect(load("10.0.0.0/8, not-a-range")).rejects.toThrow(
22
- "TRUSTED_PROXIES.1: not a CIDR range or address",
22
+ 'TRUSTED_PROXIES: parseTrustedProxies: "not-a-range" is not an IP address, a CIDR range or the keyword cloudflare',
23
23
  );
24
24
  });
25
25
 
@@ -28,3 +28,20 @@ test("comma-separated ranges are trimmed, and an empty list declares no proxy",
28
28
  expect(env.TRUSTED_PROXIES).toEqual(["10.0.0.0/8", "172.16.0.0/12"]);
29
29
  expect((await load("")).env.TRUSTED_PROXIES).toBeUndefined();
30
30
  });
31
+
32
+ test("the keyword cloudflare expands to Cloudflare's ranges, beside other entries", async () => {
33
+ const { cloudflareRanges } = await import("@alxia/core");
34
+ const { env } = await load("cloudflare, 172.16.0.0/12");
35
+ expect(env.TRUSTED_PROXIES).toEqual([...cloudflareRanges, "172.16.0.0/12"]);
36
+ });
37
+
38
+ test("the keyword is case-insensitive, and an empty entry stops the app", async () => {
39
+ const { cloudflareRanges } = await import("@alxia/core");
40
+ expect((await load("Cloudflare")).env.TRUSTED_PROXIES).toEqual([
41
+ ...cloudflareRanges,
42
+ ]);
43
+ await expect(load("10.0.0.0/8,,172.16.0.0/12")).rejects.toThrow(
44
+ "TRUSTED_PROXIES: parseTrustedProxies: entry 2 is empty",
45
+ );
46
+ await expect(load("0.0.0.0/0")).rejects.toThrow("would trust every address");
47
+ });
@@ -1,4 +1,4 @@
1
- import { trustProxy } from "@alxia/core";
1
+ import { parseTrustedProxies } from "@alxia/core";
2
2
  import { defineEnv } from "@alxia/env";
3
3
  import { z } from "zod";
4
4
 
@@ -6,23 +6,13 @@ import { z } from "zod";
6
6
  // production included, is a deployment.
7
7
  const local = ["development", "test"].includes(Bun.env.NODE_ENV ?? "");
8
8
 
9
- // A range or an address trustProxy accepts: it throws on any other.
10
- const isRange = (range: string) => {
11
- try {
12
- trustProxy({ trusted: [range], untrusted: "refuse" });
13
- return true;
14
- } catch {
15
- return false;
16
- }
17
- };
18
-
19
9
  // Checked once, when this module is first imported: a missing or malformed
20
10
  // variable stops the process, with every issue, before it listens. Secrets
21
11
  // print as `***`. API_KEY defaults to `dev-key` in development and test
22
12
  // alone: deployed, it is required. API_DOCS serves the API reference at
23
13
  // /docs: on in development, off unless set elsewhere. TRUSTED_PROXIES is
24
- // unset by default: the app then reads no forwarding header. Set it behind a
25
- // load balancer (src/context.ts).
14
+ // unset by default: the app then reads no forwarding header. Set it
15
+ // behind a load balancer (src/context.ts).
26
16
  export const env = defineEnv(
27
17
  {
28
18
  PORT: z.coerce.number().default(3000),
@@ -30,14 +20,19 @@ export const env = defineEnv(
30
20
  API_DOCS: z.stringbool().default(Bun.env.NODE_ENV === "development"),
31
21
  TRUSTED_PROXIES: z
32
22
  .string()
33
- .transform((list) =>
34
- list
35
- .split(",")
36
- .map((range) => range.trim())
37
- .filter(Boolean),
38
- )
39
- .pipe(z.array(z.string().refine(isRange, "not a CIDR range or address")))
40
- .transform((ranges) => (ranges.length > 0 ? ranges : undefined))
23
+ .transform((list, ctx) => {
24
+ try {
25
+ const ranges = parseTrustedProxies(list);
26
+ return ranges.length > 0 ? ranges : undefined;
27
+ } catch (error) {
28
+ ctx.issues.push({
29
+ code: "custom",
30
+ message: (error as Error).message,
31
+ input: list,
32
+ });
33
+ return z.NEVER;
34
+ }
35
+ })
41
36
  .optional(),
42
37
  },
43
38
  { secret: ["API_KEY"] },
@@ -5,4 +5,6 @@ PORT=3000
5
5
  # comma-separated CIDR ranges or addresses, optional, unset by default: the proxies in front of
6
6
  # the app, a load balancer's. Set, X-Forwarded-For from one of them sets ctx.ip, and a forwarding
7
7
  # header from any other connection is refused with a 403. Unset, no forwarding header is read.
8
+ # Behind Cloudflare, the keyword `cloudflare` stands for its published ranges:
9
+ # TRUSTED_PROXIES=cloudflare,172.16.0.0/12
8
10
  # TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
@@ -19,6 +19,8 @@ const viewerOf = defineMiddleware(({ request }, next) => {
19
19
 
20
20
  // The base: what every resolver reads, decorated or derived here.
21
21
  //
22
+ // Behind Cloudflare: TRUSTED_PROXIES=cloudflare,172.16.0.0/12 (`cloudflare` is
23
+ // its published ranges, then your own proxy's).
22
24
  // Behind a load balancer, set TRUSTED_PROXIES to its range: its
23
25
  // X-Forwarded-For then sets ctx.ip, and a forwarding header from any other
24
26
  // connection is refused with a 403. A request that carries none, a health
@@ -19,7 +19,7 @@ const load = async (trustedProxies: string) => {
19
19
 
20
20
  test("a malformed TRUSTED_PROXIES stops the app, naming the variable", async () => {
21
21
  await expect(load("10.0.0.0/8, not-a-range")).rejects.toThrow(
22
- "TRUSTED_PROXIES.1: not a CIDR range or address",
22
+ 'TRUSTED_PROXIES: parseTrustedProxies: "not-a-range" is not an IP address, a CIDR range or the keyword cloudflare',
23
23
  );
24
24
  });
25
25
 
@@ -28,3 +28,20 @@ test("comma-separated ranges are trimmed, and an empty list declares no proxy",
28
28
  expect(env.TRUSTED_PROXIES).toEqual(["10.0.0.0/8", "172.16.0.0/12"]);
29
29
  expect((await load("")).env.TRUSTED_PROXIES).toBeUndefined();
30
30
  });
31
+
32
+ test("the keyword cloudflare expands to Cloudflare's ranges, beside other entries", async () => {
33
+ const { cloudflareRanges } = await import("@alxia/core");
34
+ const { env } = await load("cloudflare, 172.16.0.0/12");
35
+ expect(env.TRUSTED_PROXIES).toEqual([...cloudflareRanges, "172.16.0.0/12"]);
36
+ });
37
+
38
+ test("the keyword is case-insensitive, and an empty entry stops the app", async () => {
39
+ const { cloudflareRanges } = await import("@alxia/core");
40
+ expect((await load("Cloudflare")).env.TRUSTED_PROXIES).toEqual([
41
+ ...cloudflareRanges,
42
+ ]);
43
+ await expect(load("10.0.0.0/8,,172.16.0.0/12")).rejects.toThrow(
44
+ "TRUSTED_PROXIES: parseTrustedProxies: entry 2 is empty",
45
+ );
46
+ await expect(load("0.0.0.0/0")).rejects.toThrow("would trust every address");
47
+ });
@@ -1,32 +1,27 @@
1
- import { trustProxy } from "@alxia/core";
1
+ import { parseTrustedProxies } from "@alxia/core";
2
2
  import { defineEnv } from "@alxia/env";
3
3
  import { z } from "zod";
4
4
 
5
- // A range or an address trustProxy accepts: it throws on any other.
6
- const isRange = (range: string) => {
7
- try {
8
- trustProxy({ trusted: [range], untrusted: "refuse" });
9
- return true;
10
- } catch {
11
- return false;
12
- }
13
- };
14
-
15
5
  // Checked once, when this module is first imported: a malformed variable
16
6
  // stops the process, with every issue, before it listens. TRUSTED_PROXIES is
17
- // unset by default: the app then reads no forwarding header. Set it behind a
18
- // load balancer (src/context.ts).
7
+ // unset by default: the app then reads no forwarding header. Set it
8
+ // behind a load balancer (src/context.ts).
19
9
  export const env = defineEnv({
20
10
  PORT: z.coerce.number().default(3000),
21
11
  TRUSTED_PROXIES: z
22
12
  .string()
23
- .transform((list) =>
24
- list
25
- .split(",")
26
- .map((range) => range.trim())
27
- .filter(Boolean),
28
- )
29
- .pipe(z.array(z.string().refine(isRange, "not a CIDR range or address")))
30
- .transform((ranges) => (ranges.length > 0 ? ranges : undefined))
13
+ .transform((list, ctx) => {
14
+ try {
15
+ const ranges = parseTrustedProxies(list);
16
+ return ranges.length > 0 ? ranges : undefined;
17
+ } catch (error) {
18
+ ctx.issues.push({
19
+ code: "custom",
20
+ message: (error as Error).message,
21
+ input: list,
22
+ });
23
+ return z.NEVER;
24
+ }
25
+ })
31
26
  .optional(),
32
27
  });