@facilis.dev/nitro 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +18 -2
- package/dist/config.d.ts +30 -0
- package/dist/config.js +112 -0
- package/dist/constants.d.ts +24 -0
- package/dist/constants.js +24 -0
- package/dist/facade.d.ts +37 -0
- package/dist/facade.js +121 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +14 -0
- package/dist/middleware/context.d.ts +5 -0
- package/dist/middleware/context.js +86 -0
- package/dist/middleware/cors.d.ts +10 -0
- package/dist/middleware/cors.js +34 -0
- package/dist/middleware/session.d.ts +9 -0
- package/dist/middleware/session.js +18 -0
- package/dist/module.d.ts +7 -0
- package/dist/module.js +234 -0
- package/dist/rolldown-parser.d.ts +3 -0
- package/dist/rolldown-parser.js +66 -0
- package/dist/route-metadata.d.ts +22 -0
- package/dist/route-metadata.js +161 -0
- package/dist/routes/dev-query.post.d.ts +10 -0
- package/dist/routes/dev-query.post.js +49 -0
- package/dist/routes/dev-schema.get.d.ts +9 -0
- package/dist/routes/dev-schema.get.js +34 -0
- package/dist/routes/dev-view.post.d.ts +11 -0
- package/dist/routes/dev-view.post.js +61 -0
- package/dist/routes/health.get.d.ts +8 -0
- package/dist/routes/health.get.js +18 -0
- package/dist/routes/manifest-revision.get.d.ts +8 -0
- package/dist/routes/manifest-revision.get.js +26 -0
- package/dist/routes/manifest.get.d.ts +8 -0
- package/dist/routes/manifest.get.js +68 -0
- package/dist/routes/openapi.get.d.ts +8 -0
- package/dist/routes/openapi.get.js +29 -0
- package/dist/routes/sso.d.ts +2 -0
- package/dist/routes/sso.js +216 -0
- package/dist/routes/token.post.d.ts +10 -0
- package/dist/routes/token.post.js +75 -0
- package/dist/runtime/boot-runtimes.d.ts +21 -0
- package/dist/runtime/boot-runtimes.js +38 -0
- package/dist/runtime/bootstrap.d.ts +47 -0
- package/dist/runtime/bootstrap.js +214 -0
- package/dist/runtime/config.d.ts +27 -0
- package/dist/runtime/config.js +44 -0
- package/dist/runtime/cors-policy.d.ts +16 -0
- package/dist/runtime/cors-policy.js +88 -0
- package/dist/runtime/db-bootstrap.d.ts +9 -0
- package/dist/runtime/db-bootstrap.js +87 -0
- package/dist/runtime/db-target.d.ts +21 -0
- package/dist/runtime/db-target.js +52 -0
- package/dist/runtime/dev-db-persistence.d.ts +39 -0
- package/dist/runtime/dev-db-persistence.js +124 -0
- package/dist/runtime/dev-query.d.ts +38 -0
- package/dist/runtime/dev-query.js +87 -0
- package/dist/runtime/env.d.ts +9 -0
- package/dist/runtime/env.js +14 -0
- package/dist/runtime/http-guard.d.ts +16 -0
- package/dist/runtime/http-guard.js +42 -0
- package/dist/runtime/http.d.ts +11 -0
- package/dist/runtime/http.js +18 -0
- package/dist/runtime/jobs/boot.d.ts +20 -0
- package/dist/runtime/jobs/boot.js +77 -0
- package/dist/runtime/jobs/contracts.d.ts +161 -0
- package/dist/runtime/jobs/contracts.js +1 -0
- package/dist/runtime/jobs/db-store.d.ts +21 -0
- package/dist/runtime/jobs/db-store.js +210 -0
- package/dist/runtime/jobs/definitions.d.ts +14 -0
- package/dist/runtime/jobs/definitions.js +31 -0
- package/dist/runtime/jobs/engine-support.d.ts +22 -0
- package/dist/runtime/jobs/engine-support.js +32 -0
- package/dist/runtime/jobs/engine.d.ts +6 -0
- package/dist/runtime/jobs/engine.js +261 -0
- package/dist/runtime/jobs/executor.d.ts +11 -0
- package/dist/runtime/jobs/executor.js +27 -0
- package/dist/runtime/jobs/memory-store.d.ts +7 -0
- package/dist/runtime/jobs/memory-store.js +183 -0
- package/dist/runtime/jobs/row-mapping.d.ts +28 -0
- package/dist/runtime/jobs/row-mapping.js +61 -0
- package/dist/runtime/jobs/runtime.d.ts +24 -0
- package/dist/runtime/jobs/runtime.js +86 -0
- package/dist/runtime/logging/audit-chain.d.ts +54 -0
- package/dist/runtime/logging/audit-chain.js +102 -0
- package/dist/runtime/logging/bootstrap-logging.d.ts +28 -0
- package/dist/runtime/logging/bootstrap-logging.js +26 -0
- package/dist/runtime/logging/entry.d.ts +14 -0
- package/dist/runtime/logging/entry.js +85 -0
- package/dist/runtime/logging/file-sink.d.ts +24 -0
- package/dist/runtime/logging/file-sink.js +128 -0
- package/dist/runtime/logging/log-settings.d.ts +52 -0
- package/dist/runtime/logging/log-settings.js +93 -0
- package/dist/runtime/logging/log-sink.d.ts +18 -0
- package/dist/runtime/logging/log-sink.js +22 -0
- package/dist/runtime/logging/redact.d.ts +31 -0
- package/dist/runtime/logging/redact.js +106 -0
- package/dist/runtime/logging/runtime.d.ts +25 -0
- package/dist/runtime/logging/runtime.js +114 -0
- package/dist/runtime/logging/sudo-bridge.d.ts +13 -0
- package/dist/runtime/logging/sudo-bridge.js +38 -0
- package/dist/runtime/manifest-data.d.ts +28 -0
- package/dist/runtime/manifest-data.js +70 -0
- package/dist/runtime/manifest-response.d.ts +45 -0
- package/dist/runtime/manifest-response.js +50 -0
- package/dist/runtime/manifest-sections.d.ts +20 -0
- package/dist/runtime/manifest-sections.js +59 -0
- package/dist/runtime/manifest-service.d.ts +16 -0
- package/dist/runtime/manifest-service.js +66 -0
- package/dist/runtime/project-config.d.ts +8 -0
- package/dist/runtime/project-config.js +22 -0
- package/dist/runtime/project-files.d.ts +12 -0
- package/dist/runtime/project-files.js +99 -0
- package/dist/runtime/rate-limit.d.ts +6 -0
- package/dist/runtime/rate-limit.js +6 -0
- package/dist/runtime/revision-service.d.ts +15 -0
- package/dist/runtime/revision-service.js +26 -0
- package/dist/runtime/sql.d.ts +8 -0
- package/dist/runtime/sql.js +23 -0
- package/dist/runtime/sso.d.ts +40 -0
- package/dist/runtime/sso.js +98 -0
- package/dist/runtime/state.d.ts +7 -0
- package/dist/runtime/state.js +7 -0
- package/dist/runtime/storage-keys.d.ts +9 -0
- package/dist/runtime/storage-keys.js +82 -0
- package/dist/runtime/storage-target.d.ts +25 -0
- package/dist/runtime/storage-target.js +155 -0
- package/dist/runtime/system-role.d.ts +9 -0
- package/dist/runtime/system-role.js +21 -0
- package/dist/runtime/tasks/boot.d.ts +20 -0
- package/dist/runtime/tasks/boot.js +32 -0
- package/dist/runtime/tasks/contracts.d.ts +70 -0
- package/dist/runtime/tasks/contracts.js +1 -0
- package/dist/runtime/tasks/db-store.d.ts +18 -0
- package/dist/runtime/tasks/db-store.js +139 -0
- package/dist/runtime/tasks/row-mapping.d.ts +11 -0
- package/dist/runtime/tasks/row-mapping.js +69 -0
- package/dist/runtime/tasks/runtime.d.ts +7 -0
- package/dist/runtime/tasks/runtime.js +162 -0
- package/dist/runtime/tasks/tasks-test-harness.d.ts +16 -0
- package/dist/runtime/tasks/tasks-test-harness.js +70 -0
- package/dist/runtime/tenant.d.ts +10 -0
- package/dist/runtime/tenant.js +13 -0
- package/dist/runtime/workflows/boot.d.ts +25 -0
- package/dist/runtime/workflows/boot.js +75 -0
- package/dist/runtime/workflows/contracts.d.ts +96 -0
- package/dist/runtime/workflows/contracts.js +1 -0
- package/dist/runtime/workflows/db-store.d.ts +18 -0
- package/dist/runtime/workflows/db-store.js +128 -0
- package/dist/runtime/workflows/definitions.d.ts +14 -0
- package/dist/runtime/workflows/definitions.js +50 -0
- package/dist/runtime/workflows/dispatch.d.ts +4 -0
- package/dist/runtime/workflows/dispatch.js +119 -0
- package/dist/runtime/workflows/row-mapping.d.ts +5 -0
- package/dist/runtime/workflows/row-mapping.js +38 -0
- package/dist/runtime/workflows/runner.d.ts +15 -0
- package/dist/runtime/workflows/runner.js +89 -0
- package/dist/runtime/workflows/runtime.d.ts +14 -0
- package/dist/runtime/workflows/runtime.js +129 -0
- package/dist/runtime/workflows/steps.d.ts +14 -0
- package/dist/runtime/workflows/steps.js +49 -0
- package/dist/runtime/workflows/support.d.ts +20 -0
- package/dist/runtime/workflows/support.js +36 -0
- package/dist/runtime/workflows/transitions.d.ts +8 -0
- package/dist/runtime/workflows/transitions.js +184 -0
- package/dist/runtime/workflows/workflows-test-harness.d.ts +62 -0
- package/dist/runtime/workflows/workflows-test-harness.js +178 -0
- package/dist/session-cookie.d.ts +13 -0
- package/dist/session-cookie.js +48 -0
- package/dist/storage.d.ts +50 -0
- package/dist/storage.js +118 -0
- package/dist/types.d.ts +44 -0
- package/dist/types.js +1 -0
- package/dist/virtual-ids.d.ts +17 -0
- package/dist/virtual-ids.js +17 -0
- package/dist/vite.d.ts +22 -0
- package/dist/vite.js +135 -0
- package/package.json +61 -4
- package/src/config.ts +120 -0
- package/src/constants.ts +24 -0
- package/src/facade.ts +153 -0
- package/src/index.ts +44 -0
- package/src/middleware/context.ts +106 -0
- package/src/middleware/cors.ts +42 -0
- package/src/middleware/session.ts +23 -0
- package/src/module.ts +278 -0
- package/src/rolldown-parser.ts +79 -0
- package/src/route-metadata-test-harness.ts +62 -0
- package/src/route-metadata.ts +194 -0
- package/src/routes/dev-query.post.ts +53 -0
- package/src/routes/dev-schema.get.ts +43 -0
- package/src/routes/dev-view.post.ts +66 -0
- package/src/routes/health.get.ts +26 -0
- package/src/routes/manifest-revision.get.ts +38 -0
- package/src/routes/manifest.get.ts +111 -0
- package/src/routes/openapi.get.ts +34 -0
- package/src/routes/sso.ts +247 -0
- package/src/routes/token.post.ts +89 -0
- package/src/runtime/boot-runtimes.ts +69 -0
- package/src/runtime/bootstrap.ts +300 -0
- package/src/runtime/config.ts +60 -0
- package/src/runtime/cors-policy.ts +107 -0
- package/src/runtime/db-bootstrap.ts +99 -0
- package/src/runtime/db-target.ts +87 -0
- package/src/runtime/dev-db-persistence.ts +146 -0
- package/src/runtime/dev-query.ts +124 -0
- package/src/runtime/env.ts +18 -0
- package/src/runtime/http-guard.ts +50 -0
- package/src/runtime/http.ts +30 -0
- package/src/runtime/jobs/boot.ts +97 -0
- package/src/runtime/jobs/contracts.ts +165 -0
- package/src/runtime/jobs/db-store-test-harness.ts +98 -0
- package/src/runtime/jobs/db-store.ts +273 -0
- package/src/runtime/jobs/definitions.ts +42 -0
- package/src/runtime/jobs/engine-support.ts +44 -0
- package/src/runtime/jobs/engine.ts +296 -0
- package/src/runtime/jobs/executor.ts +37 -0
- package/src/runtime/jobs/memory-store.ts +222 -0
- package/src/runtime/jobs/row-mapping.ts +67 -0
- package/src/runtime/jobs/runtime.ts +110 -0
- package/src/runtime/logging/audit-chain.ts +135 -0
- package/src/runtime/logging/bootstrap-logging.ts +62 -0
- package/src/runtime/logging/entry.ts +99 -0
- package/src/runtime/logging/file-sink.ts +157 -0
- package/src/runtime/logging/log-settings.ts +166 -0
- package/src/runtime/logging/log-sink.ts +31 -0
- package/src/runtime/logging/redact.ts +108 -0
- package/src/runtime/logging/runtime.ts +163 -0
- package/src/runtime/logging/sudo-bridge.ts +41 -0
- package/src/runtime/manifest-data.ts +103 -0
- package/src/runtime/manifest-response.ts +95 -0
- package/src/runtime/manifest-sections.ts +79 -0
- package/src/runtime/manifest-service.ts +83 -0
- package/src/runtime/project-config.ts +25 -0
- package/src/runtime/project-files.ts +103 -0
- package/src/runtime/rate-limit.ts +12 -0
- package/src/runtime/revision-service.ts +38 -0
- package/src/runtime/sql.ts +24 -0
- package/src/runtime/sso.ts +153 -0
- package/src/runtime/state.ts +7 -0
- package/src/runtime/storage-keys.ts +95 -0
- package/src/runtime/storage-target.ts +238 -0
- package/src/runtime/system-role.ts +26 -0
- package/src/runtime/tasks/boot.ts +49 -0
- package/src/runtime/tasks/contracts.ts +77 -0
- package/src/runtime/tasks/db-store.ts +191 -0
- package/src/runtime/tasks/row-mapping.ts +75 -0
- package/src/runtime/tasks/runtime.ts +192 -0
- package/src/runtime/tasks/tasks-test-harness.ts +92 -0
- package/src/runtime/tenant.ts +15 -0
- package/src/runtime/workflows/boot.ts +97 -0
- package/src/runtime/workflows/contracts.ts +114 -0
- package/src/runtime/workflows/db-store.ts +156 -0
- package/src/runtime/workflows/definitions.ts +75 -0
- package/src/runtime/workflows/dispatch.ts +148 -0
- package/src/runtime/workflows/row-mapping.ts +54 -0
- package/src/runtime/workflows/runner.ts +105 -0
- package/src/runtime/workflows/runtime.ts +161 -0
- package/src/runtime/workflows/steps.ts +74 -0
- package/src/runtime/workflows/support.ts +60 -0
- package/src/runtime/workflows/transitions.ts +259 -0
- package/src/runtime/workflows/workflows-test-harness.ts +238 -0
- package/src/session-cookie.ts +69 -0
- package/src/storage.ts +173 -0
- package/src/types.ts +51 -0
- package/src/virtual-ids.ts +18 -0
- package/src/virtual-modules.d.ts +53 -0
- package/src/vite.ts +175 -0
package/src/storage.ts
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
import { Readable } from "node:stream";
|
|
2
|
+
import type { ReadableStream as WebReadableStream } from "node:stream/web";
|
|
3
|
+
|
|
4
|
+
import { eq } from "drizzle-orm";
|
|
5
|
+
|
|
6
|
+
import {
|
|
7
|
+
DEFAULT_TENANT_ID,
|
|
8
|
+
fail,
|
|
9
|
+
type AuthContext,
|
|
10
|
+
type FacilisHandlerEvent,
|
|
11
|
+
type StorageApi,
|
|
12
|
+
} from "@facilis.dev/core";
|
|
13
|
+
import { facilisFiles, type PolicyScopedDatabase } from "@facilis.dev/db";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Route-facing helpers for binary uploads (D-053, SPEC §5.10).
|
|
17
|
+
*
|
|
18
|
+
* The framework stores the bytes and the `facilis_files` metadata; the app's own route
|
|
19
|
+
* declares the permissions, decides which entity the file belongs to and inserts the
|
|
20
|
+
* generated link row (`fileLinks`). The download route is token-only, so it can stay a
|
|
21
|
+
* public route (`permission: []`) and serve `<img>`/shared links without a cookie.
|
|
22
|
+
*/
|
|
23
|
+
export interface StoredFile {
|
|
24
|
+
readonly id: string;
|
|
25
|
+
readonly name: string;
|
|
26
|
+
readonly mime: string;
|
|
27
|
+
readonly size: number;
|
|
28
|
+
/** Signed, app-relative download URL (default TTL: storage.tokenTtlSeconds). */
|
|
29
|
+
readonly url: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface StoreUploadInput {
|
|
33
|
+
readonly event: FacilisHandlerEvent;
|
|
34
|
+
readonly db: PolicyScopedDatabase;
|
|
35
|
+
readonly storage: StorageApi;
|
|
36
|
+
readonly auth: AuthContext | null;
|
|
37
|
+
readonly file: File;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export interface SendStoredFileInput {
|
|
41
|
+
readonly db: PolicyScopedDatabase;
|
|
42
|
+
readonly storage: StorageApi;
|
|
43
|
+
readonly fileId: string;
|
|
44
|
+
readonly token: string;
|
|
45
|
+
readonly tenantId?: string;
|
|
46
|
+
/** Override the `content-disposition` filename (defaults to the stored name). */
|
|
47
|
+
readonly responseName?: string;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const DEFAULT_FILE_NAME = "file";
|
|
51
|
+
const MAX_FILE_NAME = 180;
|
|
52
|
+
const DEFAULT_MIME = "application/octet-stream";
|
|
53
|
+
const SAFE_MIME = /^[\w.+-]+\/[\w.+-]+$/;
|
|
54
|
+
|
|
55
|
+
/** Store the uploaded bytes and their metadata row; the caller inserts the link row. */
|
|
56
|
+
export async function storeUpload(input: StoreUploadInput): Promise<StoredFile | Response> {
|
|
57
|
+
const { event, db, storage, auth, file } = input;
|
|
58
|
+
if (!storage.available) return fail("storage_unavailable");
|
|
59
|
+
if (auth === null) return fail("unauthorized");
|
|
60
|
+
// Reject before reading the body into memory: the limit is the framework's, not the UI's.
|
|
61
|
+
if (file.size > storage.maxUploadBytes) {
|
|
62
|
+
return fail("file_too_large", { maxBytes: storage.maxUploadBytes, size: file.size });
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const name = sanitizeFileName(file.name);
|
|
66
|
+
const mime = sanitizeMime(file.type);
|
|
67
|
+
// Stream the multipart file straight into storage (D-117): no full-file buffer here.
|
|
68
|
+
const put = await storage.put(
|
|
69
|
+
Readable.fromWeb(file.stream() as unknown as WebReadableStream<Uint8Array>),
|
|
70
|
+
);
|
|
71
|
+
const [row] = await db
|
|
72
|
+
.insert(facilisFiles)
|
|
73
|
+
.values({ hash: put.hash, name, mime, size: put.size, ownerId: auth.userId })
|
|
74
|
+
.returning({ id: facilisFiles.id });
|
|
75
|
+
if (row === undefined) return fail("internal_error");
|
|
76
|
+
|
|
77
|
+
const tenantId = event.context.facilis?.defaultTenantId ?? DEFAULT_TENANT_ID;
|
|
78
|
+
return {
|
|
79
|
+
id: row.id,
|
|
80
|
+
name,
|
|
81
|
+
mime,
|
|
82
|
+
size: put.size,
|
|
83
|
+
url: storage.buildDownloadUrl(row.id, { tenantId, subject: auth.userId }),
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Validate the signed token, load the metadata row and return the bytes.
|
|
89
|
+
*
|
|
90
|
+
* The token binds the file id (and optionally the tenant); the row lookup runs under the
|
|
91
|
+
* request's policy scope, so a token from another deployment cannot reach a foreign row.
|
|
92
|
+
* Production streams through a driver-presigned redirect when the driver supports it.
|
|
93
|
+
*/
|
|
94
|
+
export async function sendStoredFile(input: SendStoredFileInput): Promise<Response> {
|
|
95
|
+
const { db, storage, fileId, token, tenantId } = input;
|
|
96
|
+
if (!storage.available) return fail("storage_unavailable");
|
|
97
|
+
|
|
98
|
+
const payload = storage.verifyDownloadToken(token, fileId);
|
|
99
|
+
if (payload === null) return fail("not_found");
|
|
100
|
+
if (payload.tenantId !== undefined && tenantId !== undefined && payload.tenantId !== tenantId) {
|
|
101
|
+
return fail("not_found");
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
const [row] = await db
|
|
105
|
+
.select({
|
|
106
|
+
hash: facilisFiles.hash,
|
|
107
|
+
name: facilisFiles.name,
|
|
108
|
+
mime: facilisFiles.mime,
|
|
109
|
+
size: facilisFiles.size,
|
|
110
|
+
})
|
|
111
|
+
.from(facilisFiles)
|
|
112
|
+
.where(eq(facilisFiles.id, fileId))
|
|
113
|
+
.limit(1);
|
|
114
|
+
if (row === undefined) return fail("not_found");
|
|
115
|
+
|
|
116
|
+
const name = sanitizeFileName(input.responseName ?? row.name);
|
|
117
|
+
if (storage.presignedGetUrl !== undefined) {
|
|
118
|
+
const location = await storage.presignedGetUrl(row.hash, { responseName: name });
|
|
119
|
+
return new Response(null, { status: 302, headers: { location } });
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
// Stream the plaintext straight into the response: the size header comes from the
|
|
123
|
+
// metadata row, so neither encrypted nor plaintext downloads are ever buffered whole.
|
|
124
|
+
const source = await storage.get(row.hash);
|
|
125
|
+
const body = Readable.toWeb(Readable.from(source)) as unknown as ConstructorParameters<
|
|
126
|
+
typeof Response
|
|
127
|
+
>[0];
|
|
128
|
+
return new Response(body, {
|
|
129
|
+
status: 200,
|
|
130
|
+
headers: fileHeaders(sanitizeMime(row.mime), name, row.size),
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Headers that make a user-uploaded blob safe to serve from the app origin. */
|
|
135
|
+
export function fileHeaders(mime: string, name: string, length: number): Headers {
|
|
136
|
+
return new Headers({
|
|
137
|
+
"content-type": mime,
|
|
138
|
+
"content-length": String(length),
|
|
139
|
+
// Never render an uploaded HTML/SVG document on the app origin; attachment downloads
|
|
140
|
+
// still work for links, and <img> subresources ignore the disposition.
|
|
141
|
+
"content-disposition": contentDisposition(name),
|
|
142
|
+
"x-content-type-options": "nosniff",
|
|
143
|
+
"content-security-policy": "sandbox",
|
|
144
|
+
"cache-control": "private, max-age=60",
|
|
145
|
+
});
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** Strip path separators/control characters; keep the display name users already saw. */
|
|
149
|
+
export function sanitizeFileName(value: string): string {
|
|
150
|
+
const base = value.split(/[\\/]/).pop() ?? "";
|
|
151
|
+
const cleaned = stripControlCharacters(base).trim().slice(0, MAX_FILE_NAME);
|
|
152
|
+
return cleaned.length === 0 ? DEFAULT_FILE_NAME : cleaned;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Drop C0 controls and DEL without a control-character regex (lint forbids one). */
|
|
156
|
+
function stripControlCharacters(value: string): string {
|
|
157
|
+
let out = "";
|
|
158
|
+
for (const character of value) {
|
|
159
|
+
const code = character.codePointAt(0) ?? 0;
|
|
160
|
+
if (code >= 0x20 && code !== 0x7f) out += character;
|
|
161
|
+
}
|
|
162
|
+
return out;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** Only a syntactically valid MIME type is echoed back; anything else is octet-stream. */
|
|
166
|
+
export function sanitizeMime(value: string): string {
|
|
167
|
+
return SAFE_MIME.test(value) ? value.toLowerCase() : DEFAULT_MIME;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
function contentDisposition(name: string): string {
|
|
171
|
+
const ascii = name.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_");
|
|
172
|
+
return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`;
|
|
173
|
+
}
|
package/src/types.ts
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import type { ManifestWarning } from "@facilis.dev/core";
|
|
2
|
+
|
|
3
|
+
/** HTTP methods a Facilis route file can declare (SPEC §7.3 RouteMeta.method). */
|
|
4
|
+
export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
|
|
5
|
+
|
|
6
|
+
/** Config keys the route metadata pass can extract; anything else is ignored. */
|
|
7
|
+
export type MetadataField =
|
|
8
|
+
"permission" | "dbTables" | "dbColumns" | "description" | "crossSite" | "rawSql";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* One route's statically extracted metadata.
|
|
12
|
+
*
|
|
13
|
+
* `unresolved` records which fields were not statically readable, so the OpenAPI
|
|
14
|
+
* facade can omit them instead of publishing a wrong value (SPEC §13 risk 3 / §6.9).
|
|
15
|
+
*/
|
|
16
|
+
export interface RouteMetadata {
|
|
17
|
+
method: HttpMethod;
|
|
18
|
+
/** OpenAPI-style path, e.g. `/api/todos/{id}`. */
|
|
19
|
+
path: string;
|
|
20
|
+
permission?: string | readonly string[];
|
|
21
|
+
/** True when the route is declared callable from another origin; omitted otherwise. */
|
|
22
|
+
crossSite?: boolean;
|
|
23
|
+
/** `rawSql: true` allows `db.execute` (D-157); false when absent, undefined when unreadable. */
|
|
24
|
+
rawSql?: boolean;
|
|
25
|
+
/** `[]` when the config declares none or the value is not statically readable. */
|
|
26
|
+
dbTables: readonly string[];
|
|
27
|
+
dbColumns: readonly string[];
|
|
28
|
+
description?: string;
|
|
29
|
+
unresolved: readonly MetadataField[];
|
|
30
|
+
/** Project-relative path for editor jump-to (RouteMeta.sourceFile). */
|
|
31
|
+
sourceFile?: string;
|
|
32
|
+
warnings: readonly ManifestWarning[];
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Map keyed by OpenAPI path first, then lower-case method (OpenAPI's own casing). */
|
|
36
|
+
export type RouteMetadataMap = Readonly<Record<string, Readonly<Record<string, RouteMetadata>>>>;
|
|
37
|
+
|
|
38
|
+
export interface ScanOptions {
|
|
39
|
+
/** Absolute project root; the analyzer owns the project's DSL layout (D-092). */
|
|
40
|
+
rootDir: string;
|
|
41
|
+
/** Receives warnings that belong to no route (parse/config diagnostics). */
|
|
42
|
+
onWarning?: (warning: ManifestWarning) => void;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Reserved plugin options.
|
|
47
|
+
*
|
|
48
|
+
* The analyzer derives the route layout (`server/routes/**`) from the project root (D-092),
|
|
49
|
+
* so `facilis()` takes no options today; the type stays exported for the documented API.
|
|
50
|
+
*/
|
|
51
|
+
export type FacilisOptions = Record<string, never>;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Virtual module identifiers shared by the Vite plugin (producer) and the Nitro
|
|
3
|
+
* module/runtime (consumers).
|
|
4
|
+
*
|
|
5
|
+
* The Vite plugin owns `#facilis/openapi-meta` because it needs HMR invalidation
|
|
6
|
+
* when a project source file changes: the analyzer reads the config and the consts route
|
|
7
|
+
* configs import, so routes are not the only input (D-092, SPEC §6.9 consequence); the
|
|
8
|
+
* Nitro module only needs a build-time fallback for the standalone `nitro.config.ts` case.
|
|
9
|
+
*/
|
|
10
|
+
export const VIRTUAL_CONFIG_ID = "#facilis/config";
|
|
11
|
+
export const VIRTUAL_DB_SCHEMA_ID = "#facilis/db-schema";
|
|
12
|
+
export const VIRTUAL_DB_VIEWS_ID = "#facilis/db-views";
|
|
13
|
+
export const VIRTUAL_JOBS_ID = "#facilis/jobs";
|
|
14
|
+
export const VIRTUAL_WORKFLOWS_ID = "#facilis/workflows";
|
|
15
|
+
export const VIRTUAL_OPENAPI_META_ID = "#facilis/openapi-meta";
|
|
16
|
+
|
|
17
|
+
/** Resolved ids must start with \0 so no on-disk file can shadow them. */
|
|
18
|
+
export const RESOLVED_OPENAPI_META_ID = "\0facilis:openapi-meta";
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ambient declarations for the virtual modules generated by the Nitro module.
|
|
3
|
+
* They have no on-disk counterpart, so TypeScript needs this contract.
|
|
4
|
+
*/
|
|
5
|
+
declare module "#facilis/config" {
|
|
6
|
+
const config: import("@facilis.dev/core").FacilisConfig;
|
|
7
|
+
export default config;
|
|
8
|
+
/** Absolute project root, used by runtime code that must read project files. */
|
|
9
|
+
export const projectRoot: string;
|
|
10
|
+
/** Absolute path to the project facilis.config.ts. */
|
|
11
|
+
export const configPath: string;
|
|
12
|
+
/** Raw config source captured when the module was created (revision fallback). */
|
|
13
|
+
export const configSource: string;
|
|
14
|
+
/** Set when facilis.config.ts is missing or unreadable. */
|
|
15
|
+
export const configError: string | undefined;
|
|
16
|
+
/** Framework versions reported in FacilisManifest.framework. */
|
|
17
|
+
export const coreVersion: string;
|
|
18
|
+
export const nitroVersion: string;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
declare module "#facilis/db-schema" {
|
|
22
|
+
const schema: Readonly<Record<string, unknown>>;
|
|
23
|
+
export default schema;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Every module under db/views/ plus db/views.ts, for the framework's view creation. */
|
|
27
|
+
declare module "#facilis/db-views" {
|
|
28
|
+
const modules: ReadonlyArray<Readonly<Record<string, unknown>>>;
|
|
29
|
+
export default modules;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Every definition module under server/jobs/ (one default export per file), for the job
|
|
34
|
+
* registry: nested directories are allowed, tests are skipped (D-107, docs/JOBS.md §5).
|
|
35
|
+
*/
|
|
36
|
+
declare module "#facilis/jobs" {
|
|
37
|
+
const modules: ReadonlyArray<import("./runtime/jobs/contracts.ts").JobModule>;
|
|
38
|
+
export default modules;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Every definition module under server/workflows/ (one default export per file), for the
|
|
43
|
+
* workflow registry: nested directories are allowed, tests are skipped (D-135).
|
|
44
|
+
*/
|
|
45
|
+
declare module "#facilis/workflows" {
|
|
46
|
+
const modules: ReadonlyArray<import("./runtime/workflows/contracts.ts").WorkflowModule>;
|
|
47
|
+
export default modules;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
declare module "#facilis/openapi-meta" {
|
|
51
|
+
const metadata: import("./types.ts").RouteMetadataMap;
|
|
52
|
+
export default metadata;
|
|
53
|
+
}
|
package/src/vite.ts
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { isAbsolute, relative, resolve, sep } from "node:path";
|
|
2
|
+
import type { Plugin } from "vite";
|
|
3
|
+
import type { NitroModule } from "nitro/types";
|
|
4
|
+
import { nitro } from "nitro/vite";
|
|
5
|
+
|
|
6
|
+
import type { Analysis } from "@facilis.dev/analyze";
|
|
7
|
+
|
|
8
|
+
import { loadNitroOptions } from "./config.ts";
|
|
9
|
+
import { createFacilisNitroModule } from "./module.ts";
|
|
10
|
+
import { analyzeProjectRoutes, routeMetadataFromAnalysis } from "./route-metadata.ts";
|
|
11
|
+
import type { RouteMetadataMap } from "./types.ts";
|
|
12
|
+
import { RESOLVED_OPENAPI_META_ID, VIRTUAL_OPENAPI_META_ID } from "./virtual-ids.ts";
|
|
13
|
+
|
|
14
|
+
type WarningSink = (message: string) => void;
|
|
15
|
+
|
|
16
|
+
/** Extensions the analyzer reads; a change to any of them can change the route facts. */
|
|
17
|
+
const PROJECT_FILE_PATTERN = /\.(?:[cm]?[jt]sx?|json)$/;
|
|
18
|
+
/** Directories the analyzer skips (its ALWAYS_SKIPPED set plus node_modules). */
|
|
19
|
+
const IGNORED_SEGMENTS: ReadonlySet<string> = new Set([
|
|
20
|
+
".facilis",
|
|
21
|
+
".git",
|
|
22
|
+
".output",
|
|
23
|
+
".turbo",
|
|
24
|
+
"coverage",
|
|
25
|
+
"dist",
|
|
26
|
+
"node_modules",
|
|
27
|
+
]);
|
|
28
|
+
|
|
29
|
+
export interface FacilisVitePlugin extends Plugin {
|
|
30
|
+
/** The Nitro module Vite exposes on the plugin object (SPEC §5.6). */
|
|
31
|
+
readonly nitro: NitroModule;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* `facilis()`'s return value: the framework plugin first, then Nitro's own Vite plugins.
|
|
36
|
+
*
|
|
37
|
+
* Nitro is mounted by `facilis()` so a project never imports `nitro/vite` itself and never
|
|
38
|
+
* keeps a `nitro.config.ts` (D-034): its options come from `facilis.config.ts`.
|
|
39
|
+
*/
|
|
40
|
+
export type FacilisPlugins = [FacilisVitePlugin, ...Plugin[]];
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* The Facilis Vite plugin (SPEC §5.6, Appendix E), plus the Nitro plugins it mounts.
|
|
44
|
+
*
|
|
45
|
+
* Three jobs: carry the Nitro module, deliver the project's Nitro options to Nitro, and own
|
|
46
|
+
* the framework route-metadata pass. The pass is a virtual module so project edits can be
|
|
47
|
+
* invalidated through Vite's module graph and HMR keeps /_openapi.json and
|
|
48
|
+
* /__facilis/manifest fresh (SPEC §6.9, contracts §8).
|
|
49
|
+
*/
|
|
50
|
+
export function facilis(): FacilisPlugins {
|
|
51
|
+
let root = process.cwd();
|
|
52
|
+
// One analysis per revision of the project: the mapping is cheap, the analyzer is not.
|
|
53
|
+
let analysis: Analysis | undefined;
|
|
54
|
+
let metadata: RouteMetadataMap | undefined;
|
|
55
|
+
|
|
56
|
+
const loadMetadata = (warn?: WarningSink): RouteMetadataMap => {
|
|
57
|
+
if (metadata !== undefined) return metadata;
|
|
58
|
+
analysis ??= analyzeProjectRoutes(root);
|
|
59
|
+
metadata =
|
|
60
|
+
analysis === undefined
|
|
61
|
+
? {}
|
|
62
|
+
: routeMetadataFromAnalysis(analysis, (warning) => warn?.(warning.message));
|
|
63
|
+
return metadata;
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
const invalidate = (): void => {
|
|
67
|
+
analysis = undefined;
|
|
68
|
+
metadata = undefined;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
// The analyzer reads facilis.config.ts and any project module a route config imports
|
|
72
|
+
// (D-092), so every project source file can change the route facts, not just routes.
|
|
73
|
+
const onProjectSourceChanged = (file: string): boolean => {
|
|
74
|
+
if (!isProjectSourceFile(file, root)) return false;
|
|
75
|
+
invalidate();
|
|
76
|
+
return true;
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
const plugin: FacilisVitePlugin = {
|
|
80
|
+
name: "facilis",
|
|
81
|
+
enforce: "pre",
|
|
82
|
+
nitro: createFacilisNitroModule(),
|
|
83
|
+
|
|
84
|
+
// Deliver the project's Nitro options through Vite's own `nitro` user-config key,
|
|
85
|
+
// which is what Nitro's plugin reads. `enforce: "pre"` is what makes it work: config
|
|
86
|
+
// hooks run in plugin order, so this one has already merged the `nitro` key into the
|
|
87
|
+
// user config by the time nitro:init builds its Nitro instance. Nothing about the
|
|
88
|
+
// project's plugins array (e.g. facilis() before react()) can change that.
|
|
89
|
+
async config(userConfig) {
|
|
90
|
+
const projectRoot = userConfig.root === undefined ? process.cwd() : resolve(userConfig.root);
|
|
91
|
+
return { nitro: await loadNitroOptions(projectRoot) };
|
|
92
|
+
},
|
|
93
|
+
|
|
94
|
+
configResolved(config) {
|
|
95
|
+
root = config.root;
|
|
96
|
+
},
|
|
97
|
+
|
|
98
|
+
// Warm the analysis before the first request so a broken route file surfaces as a
|
|
99
|
+
// warning during startup, not as a surprising slow first spec fetch.
|
|
100
|
+
async buildStart() {
|
|
101
|
+
loadMetadata((message) => this.warn(message));
|
|
102
|
+
},
|
|
103
|
+
|
|
104
|
+
configureServer(server) {
|
|
105
|
+
// handleHotUpdate covers changed modules; add/unlink also need an invalidation
|
|
106
|
+
// because a brand-new or deleted project file may have no module-graph entry yet.
|
|
107
|
+
server.watcher.on("all", (event, file) => {
|
|
108
|
+
if (event !== "add" && event !== "unlink" && event !== "addDir") return;
|
|
109
|
+
if (!onProjectSourceChanged(file)) return;
|
|
110
|
+
invalidateOpenApiMetaModule(server);
|
|
111
|
+
});
|
|
112
|
+
},
|
|
113
|
+
|
|
114
|
+
handleHotUpdate(context) {
|
|
115
|
+
if (!onProjectSourceChanged(context.file)) return;
|
|
116
|
+
invalidateOpenApiMetaModule(context.server);
|
|
117
|
+
// Returning void leaves the rest of the update pipeline (Nitro's own server
|
|
118
|
+
// reload for route handlers) untouched.
|
|
119
|
+
},
|
|
120
|
+
|
|
121
|
+
resolveId(id) {
|
|
122
|
+
if (id === VIRTUAL_OPENAPI_META_ID) return RESOLVED_OPENAPI_META_ID;
|
|
123
|
+
return null;
|
|
124
|
+
},
|
|
125
|
+
|
|
126
|
+
async load(id) {
|
|
127
|
+
if (id !== RESOLVED_OPENAPI_META_ID) return null;
|
|
128
|
+
return `export default ${JSON.stringify(loadMetadata((message) => this.warn(message)))};`;
|
|
129
|
+
},
|
|
130
|
+
};
|
|
131
|
+
|
|
132
|
+
return [plugin, ...nitro()];
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/** True for a file the analyzer reads, excluding generated and dependency directories. */
|
|
136
|
+
function isProjectSourceFile(file: string, root: string): boolean {
|
|
137
|
+
const projectRelative = relative(root, resolve(file));
|
|
138
|
+
if (projectRelative.length === 0 || isAbsolute(projectRelative)) return false;
|
|
139
|
+
const segments = projectRelative.split(sep);
|
|
140
|
+
if (segments[0] === "..") return false;
|
|
141
|
+
if (segments.some((segment) => IGNORED_SEGMENTS.has(segment))) return false;
|
|
142
|
+
return PROJECT_FILE_PATTERN.test(projectRelative);
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* Invalidate the virtual metadata module in every environment that may have imported
|
|
147
|
+
* it. Nitro's handlers live in an environment of their own, so the mixed (legacy)
|
|
148
|
+
* module graph alone is not enough.
|
|
149
|
+
*/
|
|
150
|
+
function invalidateOpenApiMetaModule(server: {
|
|
151
|
+
environments: Record<
|
|
152
|
+
string,
|
|
153
|
+
{
|
|
154
|
+
moduleGraph:
|
|
155
|
+
| {
|
|
156
|
+
getModuleById(id: string): { id: string | null } | undefined;
|
|
157
|
+
invalidateModule(mod: never): void;
|
|
158
|
+
}
|
|
159
|
+
| undefined;
|
|
160
|
+
}
|
|
161
|
+
>;
|
|
162
|
+
moduleGraph: {
|
|
163
|
+
getModuleById(id: string): { id: string | null } | undefined;
|
|
164
|
+
invalidateModule(mod: never): void;
|
|
165
|
+
};
|
|
166
|
+
}): void {
|
|
167
|
+
for (const environment of Object.values(server.environments)) {
|
|
168
|
+
const graph = environment.moduleGraph;
|
|
169
|
+
if (graph === undefined) continue;
|
|
170
|
+
const module = graph.getModuleById(RESOLVED_OPENAPI_META_ID);
|
|
171
|
+
if (module !== undefined) graph.invalidateModule(module as never);
|
|
172
|
+
}
|
|
173
|
+
const legacy = server.moduleGraph.getModuleById(RESOLVED_OPENAPI_META_ID);
|
|
174
|
+
if (legacy !== undefined) server.moduleGraph.invalidateModule(legacy as never);
|
|
175
|
+
}
|