@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 +2 -2
- package/docs/guide.md +25 -19
- package/docs/roadmap.md +1 -1
- package/docs/troubleshooting.md +10 -5
- package/package.json +6 -6
- package/templates/api/.env.example +2 -0
- package/templates/api/src/context.ts +2 -0
- package/templates/api/src/env.spec.ts +18 -1
- package/templates/api/src/env.ts +16 -21
- package/templates/graphql/.env.example +2 -0
- package/templates/graphql/src/context.ts +2 -0
- package/templates/graphql/src/env.spec.ts +18 -1
- package/templates/graphql/src/env.ts +16 -21
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 {
|
|
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
|
-
|
|
365
|
-
|
|
366
|
-
.
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
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
|
-
|
|
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
|
|
package/docs/troubleshooting.md
CHANGED
|
@@ -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,
|
|
734
|
-
`
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
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.
|
|
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.
|
|
45
|
-
"@alxia/env": "^0.
|
|
46
|
-
"@alxia/graphql": "^0.
|
|
47
|
-
"@alxia/openapi": "^0.6.
|
|
48
|
-
"@alxia/react-router": "^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
|
-
|
|
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
|
+
});
|
package/templates/api/src/env.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
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
|
|
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
|
-
|
|
35
|
-
|
|
36
|
-
.
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
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 {
|
|
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
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
.
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
});
|