arocapi 5.0.0-beta.6 → 5.0.0-beta.8

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.
Files changed (58) hide show
  1. package/README.md +10 -10
  2. package/dist/app.d.ts +3 -4
  3. package/dist/app.js +10 -7
  4. package/dist/app.js.map +1 -1
  5. package/dist/routes/file.d.ts +2 -2
  6. package/dist/routes/file.js +25 -72
  7. package/dist/routes/file.js.map +1 -1
  8. package/dist/routes/metadata.d.ts +5 -5
  9. package/dist/routes/metadata.js +22 -61
  10. package/dist/routes/metadata.js.map +1 -1
  11. package/dist/storage/backend.d.ts +58 -0
  12. package/dist/storage/backend.js +2 -0
  13. package/dist/storage/backend.js.map +1 -0
  14. package/dist/storage/deliver.d.ts +12 -0
  15. package/dist/storage/deliver.js +34 -0
  16. package/dist/storage/deliver.js.map +1 -0
  17. package/dist/storage/directory/directory.d.ts +6 -0
  18. package/dist/storage/directory/directory.js +24 -0
  19. package/dist/storage/directory/directory.js.map +1 -0
  20. package/dist/storage/entity-meta/entity-meta.d.ts +5 -0
  21. package/dist/storage/entity-meta/entity-meta.js +14 -0
  22. package/dist/storage/entity-meta/entity-meta.js.map +1 -0
  23. package/dist/storage/location.d.ts +20 -0
  24. package/dist/storage/location.js +40 -0
  25. package/dist/storage/location.js.map +1 -0
  26. package/dist/storage/ocfl/ocfl.d.ts +7 -0
  27. package/dist/storage/ocfl/ocfl.js +79 -0
  28. package/dist/storage/ocfl/ocfl.js.map +1 -0
  29. package/dist/storage/ocfl/ocflFs.d.ts +7 -0
  30. package/dist/storage/ocfl/ocflFs.js +33 -0
  31. package/dist/storage/ocfl/ocflFs.js.map +1 -0
  32. package/dist/storage/results.d.ts +7 -0
  33. package/dist/storage/results.js +22 -0
  34. package/dist/storage/results.js.map +1 -0
  35. package/dist/storage/s3/s3.d.ts +10 -0
  36. package/dist/storage/s3/s3.js +47 -0
  37. package/dist/storage/s3/s3.js.map +1 -0
  38. package/dist/utils/headers.d.ts +1 -1
  39. package/dist/utils/headers.js +10 -1
  40. package/dist/utils/headers.js.map +1 -1
  41. package/package.json +27 -7
  42. package/src/app.ts +32 -24
  43. package/src/routes/file.ts +23 -99
  44. package/src/routes/metadata.ts +24 -86
  45. package/src/storage/backend.ts +75 -0
  46. package/src/storage/deliver.ts +65 -0
  47. package/src/storage/directory/directory.ts +39 -0
  48. package/src/storage/entity-meta/entity-meta.ts +25 -0
  49. package/src/storage/location.ts +85 -0
  50. package/src/storage/ocfl/ocfl.ts +129 -0
  51. package/src/storage/ocfl/ocflFs.ts +67 -0
  52. package/src/storage/results.ts +32 -0
  53. package/src/storage/s3/s3.ts +79 -0
  54. package/src/utils/headers.ts +22 -2
  55. package/dist/types/fileHandlers.d.ts +0 -37
  56. package/dist/types/fileHandlers.js +0 -2
  57. package/dist/types/fileHandlers.js.map +0 -1
  58. package/src/types/fileHandlers.ts +0 -57
@@ -1,16 +1,14 @@
1
- import { createReadStream } from 'node:fs';
2
1
  import { create as contentDisposition } from 'content-disposition';
3
2
  import type { FastifyPluginAsync } from 'fastify';
4
3
  import type { ZodTypeProvider } from 'fastify-type-provider-zod';
5
4
  import { z } from 'zod';
6
5
  import type { PrismaClient } from '../generated/prisma/client.js';
6
+ import type { ContentSource } from '../storage/backend.js';
7
+ import { sendDelivery } from '../storage/deliver.js';
7
8
  import type { AccessFunction } from '../types/access.js';
8
- import type { RequestContext } from '../types/context.js';
9
- import type { FileHandler, FileMetadata } from '../types/fileHandlers.js';
10
9
  import type { EntityVisibilityFilter } from '../types/visibility.js';
11
10
  import { createAccessGuard } from '../utils/access.js';
12
11
  import { createNotFoundError } from '../utils/errors.js';
13
- import { setFileHeaders } from '../utils/headers.js';
14
12
  import { createNotVisibleResponder, type RefusalOptions } from '../utils/visibility.js';
15
13
 
16
14
  const paramsSchema = z.object({
@@ -29,29 +27,14 @@ const querySchema = z.object({
29
27
 
30
28
  type FileRouteOptions = {
31
29
  prisma: PrismaClient;
32
- fileHandler: FileHandler;
30
+ content: ContentSource;
33
31
  access: AccessFunction;
34
32
  entityVisibilityFilter: EntityVisibilityFilter;
35
33
  refusal: RefusalOptions;
36
34
  };
37
35
 
38
36
  const file: FastifyPluginAsync<FileRouteOptions> = async (fastify, opts) => {
39
- const { prisma, fileHandler, access, entityVisibilityFilter, refusal } = opts;
40
-
41
- // Split the entity off so handlers receive only the File they're typed for
42
- const findVisibleFile = async (id: string, context: RequestContext) => {
43
- const found = await prisma.file.findFirst({
44
- where: { id, entity: await entityVisibilityFilter(context) },
45
- include: { entity: { omit: { meta: true } } },
46
- });
47
- if (!found) {
48
- return null;
49
- }
50
-
51
- const { entity, ...file } = found;
52
-
53
- return { file, entity };
54
- };
37
+ const { prisma, content, access, entityVisibilityFilter, refusal } = opts;
55
38
 
56
39
  const denyContent = createAccessGuard({ access, isAuthenticated: refusal.isAuthenticated, level: 'content' });
57
40
 
@@ -61,101 +44,42 @@ const file: FastifyPluginAsync<FileRouteOptions> = async (fastify, opts) => {
61
44
  exists: async (id) => (await prisma.file.count({ where: { id } })) > 0,
62
45
  });
63
46
 
64
- fastify.withTypeProvider<ZodTypeProvider>().head(
65
- '/file/:id',
66
- {
67
- schema: {
68
- params: paramsSchema,
69
- },
47
+ fastify.withTypeProvider<ZodTypeProvider>().route({
48
+ method: ['GET', 'HEAD'],
49
+ url: '/file/:id',
50
+ schema: {
51
+ params: paramsSchema,
52
+ querystring: querySchema,
70
53
  },
71
- async (request, reply) => {
54
+ handler: async (request, reply) => {
72
55
  const { id } = request.params;
73
56
 
74
57
  const context = { request, fastify };
75
- const visible = await findVisibleFile(id, context);
58
+ const found = await prisma.file.findFirst({
59
+ where: { id, entity: await entityVisibilityFilter(context) },
60
+ include: { entity: true },
61
+ });
76
62
 
77
- if (!visible) {
63
+ if (!found) {
78
64
  return sendFileNotVisible(reply, id, context);
79
65
  }
80
66
 
81
- const { file, entity } = visible;
67
+ const { entity, ...file } = found;
82
68
  if (await denyContent(reply, entity, context)) {
83
69
  return reply;
84
70
  }
85
71
 
86
- const metadata: FileMetadata | false = await fileHandler.head(file, context);
87
-
88
- if (!metadata) {
89
- return reply.code(404).send(createNotFoundError('The requested file metadata was not found', id));
90
- }
91
-
92
- setFileHeaders(reply, metadata);
93
-
94
- return reply.code(200).send();
95
- },
96
- );
97
-
98
- fastify.withTypeProvider<ZodTypeProvider>().get(
99
- '/file/:id',
100
- {
101
- schema: {
102
- params: paramsSchema,
103
- querystring: querySchema,
104
- },
105
- },
106
- async (request, reply) => {
107
- const { id } = request.params;
108
-
109
- const context = { request, fastify };
110
- const visible = await findVisibleFile(id, context);
111
-
112
- if (!visible) {
113
- return sendFileNotVisible(reply, id, context);
114
- }
72
+ const { disposition, filename, noRedirect } = request.query;
73
+ const disposed = contentDisposition(filename || file.filename, { type: disposition });
74
+ const delivery = await content(file, entity, { ...context, contentDisposition: disposed });
115
75
 
116
- const { file, entity } = visible;
117
- if (await denyContent(reply, entity, context)) {
118
- return reply;
119
- }
120
-
121
- const result = await fileHandler.get(file, context);
122
-
123
- if (!result) {
76
+ if (!delivery) {
124
77
  return reply.code(404).send(createNotFoundError('The requested file could not be retrieved', id));
125
78
  }
126
79
 
127
- if (result.type === 'redirect') {
128
- if (request.query.noRedirect) {
129
- return reply.code(200).send({ location: result.url });
130
- }
131
-
132
- return reply.code(302).redirect(result.url);
133
- }
134
-
135
- const { disposition, filename: customFilename } = request.query;
136
- setFileHeaders(reply, result.metadata);
137
- reply.header('Content-Disposition', contentDisposition(customFilename || file.filename, { type: disposition }));
138
-
139
- // Handle stream response
140
- if (result.type === 'stream') {
141
- return reply.code(200).send(result.stream);
142
- }
143
-
144
- if (result.type === 'file') {
145
- if (result.accelPath) {
146
- reply.header('X-Accel-Redirect', result.accelPath);
147
- return reply.code(200).send();
148
- }
149
-
150
- const stream = createReadStream(result.path);
151
- return reply.code(200).send(stream);
152
- }
153
-
154
- // Exhaustiveness check - should never reach here with proper types
155
- reply.removeHeader('Content-Disposition');
156
- throw new Error(`Unexpected file result type: ${(result as { type: string }).type}`);
80
+ return sendDelivery(request, reply, delivery, { contentDisposition: disposed, noRedirect });
157
81
  },
158
- );
82
+ });
159
83
  };
160
84
 
161
85
  export default file;
@@ -1,50 +1,44 @@
1
- import { createReadStream } from 'node:fs';
2
1
  import type { FastifyPluginAsync } from 'fastify';
3
2
  import type { ZodTypeProvider } from 'fastify-type-provider-zod';
4
3
  import { z } from 'zod';
5
4
  import type { PrismaClient } from '../generated/prisma/client.js';
5
+ import type { MetadataSource } from '../storage/backend.js';
6
+ import { sendDelivery } from '../storage/deliver.js';
6
7
  import type { AccessFunction } from '../types/access.js';
7
- import type { RequestContext } from '../types/context.js';
8
- import type { FileMetadata, RoCrateHandler } from '../types/fileHandlers.js';
9
8
  import type { EntityVisibilityFilter } from '../types/visibility.js';
10
9
  import { createAccessGuard } from '../utils/access.js';
11
10
  import { createNotFoundError } from '../utils/errors.js';
12
- import { setFileHeaders } from '../utils/headers.js';
13
11
  import { createEntityNotVisibleResponder, type RefusalOptions } from '../utils/visibility.js';
14
12
 
15
13
  const paramsSchema = z.object({
16
14
  id: z.url(),
17
15
  });
18
16
 
19
- type CrateRouteOptions = {
17
+ type MetadataRouteOptions = {
20
18
  prisma: PrismaClient;
21
- roCrateHandler: RoCrateHandler;
19
+ metadata: MetadataSource;
22
20
  access: AccessFunction;
23
21
  entityVisibilityFilter: EntityVisibilityFilter;
24
22
  refusal: RefusalOptions;
25
23
  };
26
24
 
27
- const crate: FastifyPluginAsync<CrateRouteOptions> = async (fastify, opts) => {
28
- const { prisma, roCrateHandler, access, entityVisibilityFilter, refusal } = opts;
29
-
30
- const findVisibleEntity = async (id: string, context: RequestContext) =>
31
- prisma.entity.findFirst({ where: { AND: [{ id }, await entityVisibilityFilter(context)] } });
25
+ const metadataRoute: FastifyPluginAsync<MetadataRouteOptions> = async (fastify, opts) => {
26
+ const { prisma, metadata, access, entityVisibilityFilter, refusal } = opts;
32
27
 
33
28
  const sendEntityNotVisible = createEntityNotVisibleResponder(prisma, refusal);
34
29
  const denyMetadata = createAccessGuard({ access, isAuthenticated: refusal.isAuthenticated, level: 'metadata' });
35
30
 
36
- fastify.withTypeProvider<ZodTypeProvider>().head(
37
- '/entity/:id/metadata',
38
- {
39
- schema: {
40
- params: paramsSchema,
41
- },
31
+ fastify.withTypeProvider<ZodTypeProvider>().route({
32
+ method: ['GET', 'HEAD'],
33
+ url: '/entity/:id/metadata',
34
+ schema: {
35
+ params: paramsSchema,
42
36
  },
43
- async (request, reply) => {
37
+ handler: async (request, reply) => {
44
38
  const { id } = request.params;
45
39
 
46
40
  const context = { request, fastify };
47
- const entity = await findVisibleEntity(id, context);
41
+ const entity = await prisma.entity.findFirst({ where: { AND: [{ id }, await entityVisibilityFilter(context)] } });
48
42
 
49
43
  if (!entity) {
50
44
  return sendEntityNotVisible(reply, id, context);
@@ -54,76 +48,20 @@ const crate: FastifyPluginAsync<CrateRouteOptions> = async (fastify, opts) => {
54
48
  return reply;
55
49
  }
56
50
 
57
- const metadata: FileMetadata | false = await roCrateHandler.head(entity, context);
58
-
59
- if (!metadata) {
60
- return reply.code(404).send(createNotFoundError('The requested RO-Crate metadata was not found', id));
61
- }
62
-
63
- setFileHeaders(reply, metadata);
64
-
65
- return reply.code(200).send();
66
- },
67
- );
68
-
69
- fastify.withTypeProvider<ZodTypeProvider>().get(
70
- '/entity/:id/metadata',
71
- {
72
- schema: {
73
- params: paramsSchema,
74
- },
75
- },
76
- async (request, reply) => {
77
- const { id } = request.params;
78
-
79
- const context = { request, fastify };
80
- const entity = await findVisibleEntity(id, context);
81
-
82
- if (!entity) {
83
- return sendEntityNotVisible(reply, id, context);
84
- }
85
-
86
- if (await denyMetadata(reply, entity, context)) {
87
- return reply;
88
- }
89
-
90
- const result = await roCrateHandler.get(entity, context);
91
-
92
- if (!result) {
93
- return reply.code(404).send(createNotFoundError('The requested RO-Crate could not be retrieved', id));
94
- }
95
-
96
- if (result.type === 'redirect') {
97
- return reply.code(302).redirect(result.url);
98
- }
99
-
100
- // Set content type to application/ld+json for RO-Crate
101
- const metadata = {
102
- ...result.metadata,
103
- contentType: 'application/ld+json',
104
- };
105
-
106
- setFileHeaders(reply, metadata);
107
-
108
- // Handle stream response
109
- if (result.type === 'stream') {
110
- return reply.code(200).send(result.stream);
111
- }
112
-
113
- if (result.type === 'file') {
114
- if (result.accelPath) {
115
- reply.header('X-Accel-Redirect', result.accelPath);
116
- return reply.code(200).send();
117
- }
51
+ const delivery = await metadata(entity, context);
118
52
 
119
- const stream = createReadStream(result.path);
120
- return reply.code(200).send(stream);
53
+ if (!delivery) {
54
+ return reply.code(404).send(createNotFoundError('The requested Metadata was not found', id));
121
55
  }
122
56
 
123
- // Exhaustiveness check - should never reach here with proper types
124
- throw new Error(`Unexpected RO-Crate result type: ${(result as { type: string }).type}`);
57
+ return sendDelivery(
58
+ request,
59
+ reply,
60
+ delivery.type === 'redirect' ? delivery : { ...delivery, contentType: 'application/ld+json' },
61
+ { json: true },
62
+ );
125
63
  },
126
- );
64
+ });
127
65
  };
128
66
 
129
- export default crate;
67
+ export default metadataRoute;
@@ -0,0 +1,75 @@
1
+ import type { Readable } from 'node:stream';
2
+ import type { Entity, File } from '../generated/prisma/client.js';
3
+ import type { RequestContext } from '../types/context.js';
4
+
5
+ export type MaybePromise<T> = T | Promise<T>;
6
+
7
+ /**
8
+ * Headers a `stream` or `path` delivery carries, read from storage rather than the database
9
+ */
10
+ export type DeliveryHeaders = {
11
+ contentLength: number;
12
+ etag?: string;
13
+ lastModified?: Date;
14
+ };
15
+
16
+ /** Bytes the library streams; `open` is called only on GET */
17
+ export type StreamDelivery = { type: 'stream'; open: () => MaybePromise<Readable> } & DeliveryHeaders;
18
+
19
+ /** An absolute path on disk the library opens on GET */
20
+ export type PathDelivery = { type: 'path'; path: string } & DeliveryHeaders;
21
+
22
+ /** A URL the client is sent to: 302, or 200 `{ location }` under `?noRedirect=true` */
23
+ export type RedirectDelivery = { type: 'redirect'; url: string };
24
+
25
+ /** A value the library serialises once, with the length and a strong ETag from those bytes */
26
+ export type JsonDelivery = { type: 'json'; value: unknown };
27
+
28
+ /** Content's `stream` and `path` deliveries name their Content-Type; Metadata's is always `application/ld+json` */
29
+ export type ContentDelivery =
30
+ | (StreamDelivery & { contentType: string })
31
+ | (PathDelivery & { contentType: string })
32
+ | RedirectDelivery;
33
+
34
+ export type MetadataDelivery = StreamDelivery | PathDelivery | RedirectDelivery | JsonDelivery;
35
+
36
+ export type ContentContext = RequestContext & {
37
+ /** The `Content-Disposition` the library sends on `stream` and `path` deliveries, for baking into a redirect */
38
+ contentDisposition: string;
39
+ };
40
+
41
+ /**
42
+ * Deliver an entity's Metadata, or `null` for a 404; HEAD and GET make the same call
43
+ */
44
+ export type MetadataSource = (entity: Entity, context: RequestContext) => MaybePromise<MetadataDelivery | null>;
45
+
46
+ /**
47
+ * Deliver a file's Content, or `null` for a 404; `entity` is the file's entity, with its `meta`
48
+ */
49
+ export type ContentSource = (
50
+ file: File,
51
+ entity: Entity,
52
+ context: ContentContext,
53
+ ) => MaybePromise<ContentDelivery | null>;
54
+
55
+ export type StorageBackend = { metadata: MetadataSource; content: ContentSource };
56
+
57
+ /**
58
+ * Where a stored reference backend finds each item, overriding the default key it reads from `meta`
59
+ */
60
+ export type StorageLocate<Key = string> = {
61
+ metadata?: (entity: Entity) => MaybePromise<Key | null>;
62
+ content?: (file: File, entity: Entity) => MaybePromise<Key | null>;
63
+ };
64
+
65
+ /** What `DirectoryStorage` reads from `File.meta` and `Entity.meta`: a path relative to its root */
66
+ export type DirectoryStorageMeta = { storagePath: string };
67
+
68
+ /** What `S3Storage` reads from `File.meta` and `Entity.meta`: a key relative to the bucket */
69
+ export type S3StorageMeta = { storageKey: string };
70
+
71
+ /** What `OcflStorage` reads from `File.meta` and `Entity.meta`; Metadata's `ocflPath` defaults to `ro-crate-metadata.json` */
72
+ export type OcflStorageMeta = { ocflObject: string; ocflPath?: string };
73
+
74
+ /** An OCFL object id and a logical path inside its head version */
75
+ export type OcflLocation = { object: string; path: string };
@@ -0,0 +1,65 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { open } from 'node:fs/promises';
3
+ import type { Readable } from 'node:stream';
4
+ import type { FastifyReply, FastifyRequest } from 'fastify';
5
+ import { setDeliveryHeaders } from '../utils/headers.js';
6
+ import type { ContentDelivery, JsonDelivery } from './backend.js';
7
+
8
+ type SendOptions = {
9
+ contentDisposition?: string;
10
+ noRedirect?: boolean;
11
+ /** Whether a `json` delivery may be sent: Metadata's only */
12
+ json?: boolean;
13
+ };
14
+
15
+ /** A delivery with its Content-Type settled: Content's own, or the one the Metadata route gives */
16
+ type TypedDelivery = ContentDelivery | (JsonDelivery & { contentType: string });
17
+
18
+ /**
19
+ * Turn a delivery into the response, opening bytes only on GET so HEAD sends GET's headers alone
20
+ * Throws on a delivery type the caller doesn't take, as a half typed loosely at runtime could return one
21
+ */
22
+ export const sendDelivery = async (
23
+ request: FastifyRequest,
24
+ reply: FastifyReply,
25
+ delivery: TypedDelivery,
26
+ { contentDisposition, noRedirect = false, json = false }: SendOptions = {},
27
+ ) => {
28
+ if (delivery.type === 'redirect') {
29
+ return noRedirect ? reply.code(200).send({ location: delivery.url }) : reply.redirect(delivery.url, 302);
30
+ }
31
+
32
+ const head = request.method === 'HEAD';
33
+
34
+ if (delivery.type === 'json' && json) {
35
+ const body = Buffer.from(JSON.stringify(delivery.value));
36
+ const etag = `"${createHash('sha256').update(body).digest('base64url')}"`;
37
+ setDeliveryHeaders(reply, { contentType: delivery.contentType, contentLength: body.length, etag });
38
+
39
+ return reply.code(200).send(head ? undefined : body);
40
+ }
41
+
42
+ if (delivery.type !== 'stream' && delivery.type !== 'path') {
43
+ throw new Error(
44
+ `Storage returned a delivery of type ${JSON.stringify(delivery.type)}, which this route can't send`,
45
+ );
46
+ }
47
+
48
+ // Opened before any header is set, so a failure leaves a clean 500
49
+ let body: Readable | undefined;
50
+ if (!head) {
51
+ body = delivery.type === 'stream' ? await delivery.open() : (await open(delivery.path)).createReadStream();
52
+ }
53
+
54
+ try {
55
+ setDeliveryHeaders(reply, delivery);
56
+ } catch (error) {
57
+ body?.destroy();
58
+ throw error;
59
+ }
60
+ if (contentDisposition) {
61
+ reply.header('Content-Disposition', contentDisposition);
62
+ }
63
+
64
+ return reply.code(200).send(body);
65
+ };
@@ -0,0 +1,39 @@
1
+ import { stat } from 'node:fs/promises';
2
+ import { join, resolve } from 'node:path';
3
+ import type { DirectoryStorageMeta, PathDelivery, StorageBackend, StorageLocate } from '../backend.js';
4
+ import { keyLocator } from '../location.js';
5
+ import { nullIfMissing, pathDelivery, withContentType } from '../results.js';
6
+
7
+ export type DirectoryStorageOptions = {
8
+ /** The directory every Storage key is relative to */
9
+ root: string;
10
+ /** Where each item sits below `root`, instead of `meta.storagePath` */
11
+ locate?: StorageLocate;
12
+ };
13
+
14
+ /**
15
+ * Serve Metadata and Content as files below `root`, found from `Entity.meta.storagePath` and `File.meta.storagePath`
16
+ */
17
+ export const DirectoryStorage = ({ root, locate = {} }: DirectoryStorageOptions): StorageBackend => {
18
+ const base = resolve(root);
19
+ const keys = keyLocator<DirectoryStorageMeta>(locate, 'storagePath');
20
+
21
+ const deliver = async (key: string | null): Promise<PathDelivery | null> => {
22
+ if (key === null) {
23
+ return null;
24
+ }
25
+
26
+ const path = join(base, key);
27
+ const stats = await nullIfMissing(stat(path));
28
+ if (!stats?.isFile()) {
29
+ return null;
30
+ }
31
+
32
+ return pathDelivery(path, stats, `W/"${stats.size.toString(16)}-${stats.mtime.getTime().toString(16)}"`);
33
+ };
34
+
35
+ return {
36
+ metadata: async (entity) => deliver(await keys.metadata(entity)),
37
+ content: async (file, entity) => withContentType(await deliver(await keys.content(file, entity)), file.mediaType),
38
+ };
39
+ };
@@ -0,0 +1,25 @@
1
+ import type { MetadataSource } from '../backend.js';
2
+ import { isJsonObject, metaValue } from '../location.js';
3
+
4
+ export type EntityMetaMetadataOptions = {
5
+ /** The key in `Entity.meta` holding the RO-Crate metadata object */
6
+ key?: string;
7
+ };
8
+
9
+ /**
10
+ * Serve Metadata from the JSON object at `Entity.meta.rocrate`, or another `key`; a Metadata half only
11
+ */
12
+ export const EntityMetaMetadata = ({ key = 'rocrate' }: EntityMetaMetadataOptions = {}): MetadataSource => {
13
+ return async (entity) => {
14
+ const value = metaValue(entity.meta, key);
15
+ if (value === undefined) {
16
+ return null;
17
+ }
18
+
19
+ if (!isJsonObject(value)) {
20
+ throw new Error(`${entity.id} has a meta.${key} that is not a JSON object`);
21
+ }
22
+
23
+ return { type: 'json', value };
24
+ };
25
+ };
@@ -0,0 +1,85 @@
1
+ import { isAbsolute, relative, sep } from 'node:path';
2
+ import type { Entity, File, Prisma } from '../generated/prisma/client.js';
3
+ import type { StorageLocate } from './backend.js';
4
+
5
+ export const isJsonObject = (value: Prisma.JsonValue | undefined): value is Prisma.JsonObject =>
6
+ typeof value === 'object' && value !== null && !Array.isArray(value);
7
+
8
+ /** The value at `key` in `meta`, or `undefined` when `meta` isn't an object */
9
+ export const metaValue = (meta: Prisma.JsonValue, key: string) => (isJsonObject(meta) ? meta[key] : undefined);
10
+
11
+ /**
12
+ * Read a key of the `meta` shape `Meta`: `null` when absent, a throw naming the entity and key when not a string,
13
+ * `null` included
14
+ */
15
+ export const metaString = <Meta>(meta: Prisma.JsonValue, id: string, key: Extract<keyof Meta, string>) => {
16
+ const value = metaValue(meta, key);
17
+ if (value === undefined) {
18
+ return null;
19
+ }
20
+
21
+ if (typeof value !== 'string') {
22
+ throw new Error(`${id} has a meta.${key} that is not a string`);
23
+ }
24
+
25
+ return value;
26
+ };
27
+
28
+ /**
29
+ * Refuse a Storage key that could escape its root: absolute, or with a `..` segment
30
+ */
31
+ export const safeKey = (key: string, id: string) => {
32
+ if (isAbsolute(key) || key.split(/[\\/]/).includes('..')) {
33
+ throw new Error(`${id} has an unsafe storage key ${JSON.stringify(key)}`);
34
+ }
35
+
36
+ return key;
37
+ };
38
+
39
+ /** Whether `path` is strictly below `root` */
40
+ export const inside = (root: string, path: string) => {
41
+ const rel = relative(root, path);
42
+
43
+ return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
44
+ };
45
+
46
+ type DefaultKeys<Key> = {
47
+ metadata: (entity: Entity) => Key | null;
48
+ content: (file: File) => Key | null;
49
+ };
50
+
51
+ /**
52
+ * Find each item's key from `locate`, or else from `meta`, throwing through `check` on an unsafe one
53
+ */
54
+ export const locator = <Key>(
55
+ locate: StorageLocate<Key>,
56
+ defaults: DefaultKeys<Key>,
57
+ check: (key: Key, id: string) => unknown,
58
+ ) => {
59
+ const checked = (key: Key | null, id: string) => {
60
+ if (key !== null) {
61
+ check(key, id);
62
+ }
63
+
64
+ return key;
65
+ };
66
+
67
+ return {
68
+ metadata: async (entity: Entity) => checked(await (locate.metadata ?? defaults.metadata)(entity), entity.id),
69
+ content: async (file: File, entity: Entity) =>
70
+ checked(await (locate.content ?? defaults.content)(file, entity), file.id),
71
+ };
72
+ };
73
+
74
+ /**
75
+ * A `locator` for string keys read from the same `meta` key of `Meta` on entities and files
76
+ */
77
+ export const keyLocator = <Meta>(locate: StorageLocate, key: Extract<keyof Meta, string>) =>
78
+ locator(
79
+ locate,
80
+ {
81
+ metadata: (entity) => metaString<Meta>(entity.meta, entity.id, key),
82
+ content: (file) => metaString<Meta>(file.meta, file.id, key),
83
+ },
84
+ safeKey,
85
+ );