arocapi 4.0.1 → 5.0.0-beta.10

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 (242) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +37 -781
  3. package/dist/app.d.ts +38 -21
  4. package/dist/app.js +63 -45
  5. package/dist/app.js.map +1 -1
  6. package/dist/routes/capabilities.d.ts +7 -0
  7. package/dist/routes/capabilities.js +13 -0
  8. package/dist/routes/capabilities.js.map +1 -0
  9. package/dist/routes/entities.d.ts +5 -2
  10. package/dist/routes/entities.js +38 -58
  11. package/dist/routes/entities.js.map +1 -1
  12. package/dist/routes/entity.d.ts +7 -2
  13. package/dist/routes/entity.js +14 -30
  14. package/dist/routes/entity.js.map +1 -1
  15. package/dist/routes/file.d.ts +8 -2
  16. package/dist/routes/file.js +38 -73
  17. package/dist/routes/file.js.map +1 -1
  18. package/dist/routes/files.d.ts +5 -2
  19. package/dist/routes/files.js +25 -40
  20. package/dist/routes/files.js.map +1 -1
  21. package/dist/routes/metadata.d.ts +15 -0
  22. package/dist/routes/metadata.js +38 -0
  23. package/dist/routes/metadata.js.map +1 -0
  24. package/dist/routes/search.d.ts +8 -7
  25. package/dist/routes/search.js +91 -120
  26. package/dist/routes/search.js.map +1 -1
  27. package/dist/search/advanced.d.ts +8 -0
  28. package/dist/search/advanced.js +198 -0
  29. package/dist/search/advanced.js.map +1 -0
  30. package/dist/search/backend.d.ts +95 -0
  31. package/dist/search/backend.js +5 -0
  32. package/dist/search/backend.js.map +1 -0
  33. package/dist/search/fields.d.ts +63 -0
  34. package/dist/search/fields.js +203 -0
  35. package/dist/search/fields.js.map +1 -0
  36. package/dist/search/opensearch/advanced.d.ts +4 -0
  37. package/dist/search/opensearch/advanced.js +28 -0
  38. package/dist/search/opensearch/advanced.js.map +1 -0
  39. package/dist/search/opensearch/opensearch.d.ts +16 -0
  40. package/dist/search/opensearch/opensearch.js +187 -0
  41. package/dist/search/opensearch/opensearch.js.map +1 -0
  42. package/dist/search/opensearch/visibility.d.ts +3 -0
  43. package/dist/search/opensearch/visibility.js +27 -0
  44. package/dist/search/opensearch/visibility.js.map +1 -0
  45. package/dist/search/postgres/advanced.d.ts +7 -0
  46. package/dist/search/postgres/advanced.js +54 -0
  47. package/dist/search/postgres/advanced.js.map +1 -0
  48. package/dist/search/postgres/facets.d.ts +2 -0
  49. package/dist/search/postgres/facets.js +27 -0
  50. package/dist/search/postgres/facets.js.map +1 -0
  51. package/dist/search/postgres/geo.d.ts +6 -0
  52. package/dist/search/postgres/geo.js +42 -0
  53. package/dist/search/postgres/geo.js.map +1 -0
  54. package/dist/search/postgres/postgres.d.ts +19 -0
  55. package/dist/search/postgres/postgres.js +157 -0
  56. package/dist/search/postgres/postgres.js.map +1 -0
  57. package/dist/search/postgres/values.d.ts +8 -0
  58. package/dist/search/postgres/values.js +20 -0
  59. package/dist/search/postgres/values.js.map +1 -0
  60. package/dist/search/postgres/visibility.d.ts +4 -0
  61. package/dist/search/postgres/visibility.js +38 -0
  62. package/dist/search/postgres/visibility.js.map +1 -0
  63. package/dist/search/requestFilters.d.ts +39 -0
  64. package/dist/search/requestFilters.js +125 -0
  65. package/dist/search/requestFilters.js.map +1 -0
  66. package/dist/search/visibility.d.ts +51 -0
  67. package/dist/search/visibility.js +100 -0
  68. package/dist/search/visibility.js.map +1 -0
  69. package/dist/storage/backend.d.ts +58 -0
  70. package/dist/storage/backend.js +2 -0
  71. package/dist/storage/backend.js.map +1 -0
  72. package/dist/storage/deliver.d.ts +12 -0
  73. package/dist/storage/deliver.js +34 -0
  74. package/dist/storage/deliver.js.map +1 -0
  75. package/dist/storage/directory/directory.d.ts +6 -0
  76. package/dist/storage/directory/directory.js +24 -0
  77. package/dist/storage/directory/directory.js.map +1 -0
  78. package/dist/storage/entity-meta/entity-meta.d.ts +5 -0
  79. package/dist/storage/entity-meta/entity-meta.js +14 -0
  80. package/dist/storage/entity-meta/entity-meta.js.map +1 -0
  81. package/dist/storage/location.d.ts +19 -0
  82. package/dist/storage/location.js +36 -0
  83. package/dist/storage/location.js.map +1 -0
  84. package/dist/storage/ocfl/ocfl.d.ts +6 -0
  85. package/dist/storage/ocfl/ocfl.js +45 -0
  86. package/dist/storage/ocfl/ocfl.js.map +1 -0
  87. package/dist/storage/results.d.ts +7 -0
  88. package/dist/storage/results.js +22 -0
  89. package/dist/storage/results.js.map +1 -0
  90. package/dist/storage/s3/s3.d.ts +10 -0
  91. package/dist/storage/s3/s3.js +47 -0
  92. package/dist/storage/s3/s3.js.map +1 -0
  93. package/dist/transformers/default.d.ts +11 -22
  94. package/dist/transformers/default.js +41 -15
  95. package/dist/transformers/default.js.map +1 -1
  96. package/dist/types/access.d.ts +9 -0
  97. package/dist/types/access.js +2 -0
  98. package/dist/types/access.js.map +1 -0
  99. package/dist/types/context.d.ts +6 -0
  100. package/dist/types/context.js +2 -0
  101. package/dist/types/context.js.map +1 -0
  102. package/dist/types/transformers.d.ts +4 -10
  103. package/dist/types/visibility.d.ts +6 -0
  104. package/dist/types/visibility.js +2 -0
  105. package/dist/types/visibility.js.map +1 -0
  106. package/dist/utils/access.d.ts +17 -0
  107. package/dist/utils/access.js +41 -0
  108. package/dist/utils/access.js.map +1 -0
  109. package/dist/utils/errors.d.ts +19 -10
  110. package/dist/utils/errors.js +44 -8
  111. package/dist/utils/errors.js.map +1 -1
  112. package/dist/utils/headers.d.ts +1 -1
  113. package/dist/utils/headers.js +10 -1
  114. package/dist/utils/headers.js.map +1 -1
  115. package/dist/utils/validation.d.ts +2 -0
  116. package/dist/utils/validation.js +8 -0
  117. package/dist/utils/validation.js.map +1 -0
  118. package/dist/utils/visibility.d.ts +18 -0
  119. package/dist/utils/visibility.js +16 -0
  120. package/dist/utils/visibility.js.map +1 -0
  121. package/package.json +84 -45
  122. package/prisma/models/entity.prisma +9 -8
  123. package/prisma/models/entitySearch.prisma +21 -0
  124. package/prisma/models/file.prisma +3 -3
  125. package/src/app.ts +169 -102
  126. package/src/routes/capabilities.ts +22 -0
  127. package/src/routes/entities.ts +49 -68
  128. package/src/routes/entity.ts +22 -36
  129. package/src/routes/file.ts +54 -104
  130. package/src/routes/files.ts +32 -48
  131. package/src/routes/metadata.ts +67 -0
  132. package/src/routes/search.ts +132 -152
  133. package/src/search/advanced.ts +258 -0
  134. package/src/search/backend.ts +91 -0
  135. package/src/search/fields.ts +320 -0
  136. package/src/search/opensearch/advanced.ts +36 -0
  137. package/src/search/opensearch/opensearch.ts +290 -0
  138. package/src/search/opensearch/visibility.ts +38 -0
  139. package/src/search/postgres/advanced.ts +76 -0
  140. package/src/search/postgres/facets.ts +34 -0
  141. package/src/search/postgres/geo.ts +58 -0
  142. package/src/search/postgres/postgres.ts +232 -0
  143. package/src/search/postgres/values.ts +33 -0
  144. package/src/search/postgres/visibility.ts +54 -0
  145. package/src/search/requestFilters.ts +178 -0
  146. package/src/search/visibility.ts +193 -0
  147. package/src/storage/backend.ts +75 -0
  148. package/src/storage/deliver.ts +65 -0
  149. package/src/storage/directory/directory.ts +39 -0
  150. package/src/storage/entity-meta/entity-meta.ts +25 -0
  151. package/src/storage/location.ts +78 -0
  152. package/src/storage/ocfl/ocfl.ts +71 -0
  153. package/src/storage/results.ts +32 -0
  154. package/src/storage/s3/s3.ts +79 -0
  155. package/src/transformers/default.ts +115 -85
  156. package/src/types/access.ts +25 -0
  157. package/src/types/context.ts +15 -0
  158. package/src/types/transformers.ts +8 -34
  159. package/src/types/visibility.ts +21 -0
  160. package/src/utils/access.ts +80 -0
  161. package/src/utils/errors.ts +68 -11
  162. package/src/utils/headers.ts +22 -2
  163. package/src/utils/validation.ts +11 -0
  164. package/src/utils/visibility.ts +56 -0
  165. package/dist/app.test.d.ts +0 -1
  166. package/dist/app.test.js +0 -89
  167. package/dist/app.test.js.map +0 -1
  168. package/dist/express.d.ts +0 -4
  169. package/dist/express.js +0 -14
  170. package/dist/express.js.map +0 -1
  171. package/dist/index.dev.d.ts +0 -1
  172. package/dist/index.dev.js +0 -156
  173. package/dist/index.dev.js.map +0 -1
  174. package/dist/routes/crate.d.ts +0 -9
  175. package/dist/routes/crate.js +0 -82
  176. package/dist/routes/crate.js.map +0 -1
  177. package/dist/routes/crate.test.d.ts +0 -1
  178. package/dist/routes/crate.test.js +0 -342
  179. package/dist/routes/crate.test.js.map +0 -1
  180. package/dist/routes/entities.test.d.ts +0 -1
  181. package/dist/routes/entities.test.js +0 -273
  182. package/dist/routes/entities.test.js.map +0 -1
  183. package/dist/routes/entity.test.d.ts +0 -1
  184. package/dist/routes/entity.test.js +0 -130
  185. package/dist/routes/entity.test.js.map +0 -1
  186. package/dist/routes/file.test.d.ts +0 -1
  187. package/dist/routes/file.test.js +0 -315
  188. package/dist/routes/file.test.js.map +0 -1
  189. package/dist/routes/files.test.d.ts +0 -1
  190. package/dist/routes/files.test.js +0 -222
  191. package/dist/routes/files.test.js.map +0 -1
  192. package/dist/routes/search.test.d.ts +0 -1
  193. package/dist/routes/search.test.js +0 -780
  194. package/dist/routes/search.test.js.map +0 -1
  195. package/dist/test/helpers/fastify.d.ts +0 -9
  196. package/dist/test/helpers/fastify.js +0 -18
  197. package/dist/test/helpers/fastify.js.map +0 -1
  198. package/dist/test/integration.setup.d.ts +0 -29
  199. package/dist/test/integration.setup.js +0 -188
  200. package/dist/test/integration.setup.js.map +0 -1
  201. package/dist/test/integration.test.d.ts +0 -1
  202. package/dist/test/integration.test.js +0 -396
  203. package/dist/test/integration.test.js.map +0 -1
  204. package/dist/transformers/default.test.d.ts +0 -1
  205. package/dist/transformers/default.test.js +0 -163
  206. package/dist/transformers/default.test.js.map +0 -1
  207. package/dist/transformers/transformer.test.d.ts +0 -1
  208. package/dist/transformers/transformer.test.js +0 -187
  209. package/dist/transformers/transformer.test.js.map +0 -1
  210. package/dist/types/fileHandlers.d.ts +0 -41
  211. package/dist/types/fileHandlers.js +0 -2
  212. package/dist/types/fileHandlers.js.map +0 -1
  213. package/dist/utils/errors.test.d.ts +0 -1
  214. package/dist/utils/errors.test.js +0 -66
  215. package/dist/utils/errors.test.js.map +0 -1
  216. package/dist/utils/queryBuilder.d.ts +0 -35
  217. package/dist/utils/queryBuilder.js +0 -98
  218. package/dist/utils/queryBuilder.js.map +0 -1
  219. package/prisma.config.ts +0 -9
  220. package/src/app.test.ts +0 -119
  221. package/src/express.ts +0 -21
  222. package/src/index.dev.ts +0 -200
  223. package/src/reset.d.ts +0 -1
  224. package/src/routes/__snapshots__/entities.test.ts.snap +0 -96
  225. package/src/routes/__snapshots__/entity.test.ts.snap +0 -74
  226. package/src/routes/__snapshots__/search.test.ts.snap +0 -165
  227. package/src/routes/crate.test.ts +0 -423
  228. package/src/routes/crate.ts +0 -123
  229. package/src/routes/entities.test.ts +0 -320
  230. package/src/routes/entity.test.ts +0 -160
  231. package/src/routes/file.test.ts +0 -395
  232. package/src/routes/files.test.ts +0 -278
  233. package/src/routes/search.test.ts +0 -903
  234. package/src/test/__snapshots__/integration.test.ts.snap +0 -18
  235. package/src/test/helpers/fastify.ts +0 -27
  236. package/src/test/integration.setup.ts +0 -210
  237. package/src/test/integration.test.ts +0 -482
  238. package/src/transformers/default.test.ts +0 -184
  239. package/src/transformers/transformer.test.ts +0 -252
  240. package/src/types/fileHandlers.ts +0 -65
  241. package/src/utils/errors.test.ts +0 -75
  242. package/src/utils/queryBuilder.ts +0 -132
@@ -0,0 +1,193 @@
1
+ import {
2
+ DATE_FORMS,
3
+ type FieldDeclaration,
4
+ type FieldDeclarations,
5
+ type FieldType,
6
+ type Scalar,
7
+ storeScalar,
8
+ withId,
9
+ } from './fields.js';
10
+
11
+ type ValueOf<Type extends FieldType> = Type extends 'number'
12
+ ? number
13
+ : Type extends 'boolean'
14
+ ? boolean
15
+ : Type extends 'date'
16
+ ? string | Date
17
+ : string;
18
+
19
+ type Equality<Value> = {
20
+ equals?: Value | null;
21
+ not?: Value | null;
22
+ in?: Value[];
23
+ notIn?: Value[];
24
+ };
25
+
26
+ type Ordered<Value> = { lt?: Value; lte?: Value; gt?: Value; gte?: Value };
27
+
28
+ type ConditionOf<Type extends FieldType> = Type extends 'date' | 'number'
29
+ ? ValueOf<Type> | null | (Equality<ValueOf<Type>> & Ordered<ValueOf<Type>>)
30
+ : ValueOf<Type> | null | Equality<ValueOf<Type>>;
31
+
32
+ type AnyCondition = ConditionOf<Exclude<FieldType, 'geo'>>;
33
+
34
+ type TypedWhere<Fields extends FieldDeclarations> = {
35
+ AND?: TypedWhere<Fields>[];
36
+ OR?: TypedWhere<Fields>[];
37
+ NOT?: TypedWhere<Fields>[];
38
+ id?: ConditionOf<'keyword'>;
39
+ } & {
40
+ -readonly [Name in keyof Fields as Fields[Name]['type'] extends 'geo' ? never : Name]?: ConditionOf<
41
+ Fields[Name]['type']
42
+ >;
43
+ };
44
+
45
+ type UntypedWhere = {
46
+ AND?: UntypedWhere[];
47
+ OR?: UntypedWhere[];
48
+ NOT?: UntypedWhere[];
49
+ [name: string]: AnyCondition | UntypedWhere[] | undefined;
50
+ };
51
+
52
+ /**
53
+ * A search visibility filter's condition over `id` and the declared fields, which every search backend applies
54
+ */
55
+ export type SearchVisibilityWhere<Fields extends FieldDeclarations = FieldDeclarations> = string extends keyof Fields
56
+ ? UntypedWhere
57
+ : TypedWhere<Fields>;
58
+
59
+ /**
60
+ * A checked search visibility filter, with dates as UTC instants
61
+ */
62
+ export type VisibilityCondition =
63
+ | { type: 'and' | 'or'; clauses: VisibilityCondition[] }
64
+ | { type: 'not'; clause: VisibilityCondition }
65
+ | { type: 'in'; field: string; values: Scalar[] }
66
+ | { type: 'present'; field: string }
67
+ | { type: 'range'; field: string; bounds: Partial<Record<'lt' | 'lte' | 'gt' | 'gte', number | Date>> };
68
+
69
+ const COMBINATORS = ['AND', 'OR', 'NOT'] as const;
70
+ const EQUALITY = ['equals', 'not', 'in', 'notIn'];
71
+ const RANGE = ['lt', 'lte', 'gt', 'gte'] as const;
72
+
73
+ const isPlainObject = (value: unknown): value is Record<string, unknown> => {
74
+ if (typeof value !== 'object' || value === null) {
75
+ return false;
76
+ }
77
+ const prototype = Object.getPrototypeOf(value);
78
+
79
+ return prototype === Object.prototype || prototype === null;
80
+ };
81
+
82
+ /**
83
+ * Check a search visibility filter against the field declarations, throwing an `Error` naming the field on any fault
84
+ */
85
+ export const checkSearchVisibility = (fields: FieldDeclarations, where: unknown): VisibilityCondition => {
86
+ const declarations = withId(fields);
87
+ const fail = (key: string, problem: string): never => {
88
+ throw new Error(`Search visibility filter: "${key}" ${problem}`);
89
+ };
90
+
91
+ const scalar = (field: string, type: FieldType, value: unknown): Scalar => {
92
+ if (type === 'date' && value instanceof Date && !Number.isNaN(value.getTime())) {
93
+ return value;
94
+ }
95
+
96
+ const stored = storeScalar(type, value);
97
+ if ('problem' in stored) {
98
+ const problem = type === 'date' ? `must be a Date or ${DATE_FORMS}` : stored.problem;
99
+
100
+ return fail(field, `${problem}, not ${JSON.stringify(value)}`);
101
+ }
102
+
103
+ return stored.value as Scalar;
104
+ };
105
+
106
+ const equals = (field: string, type: FieldType, value: unknown): VisibilityCondition =>
107
+ value === null
108
+ ? { type: 'not', clause: { type: 'present', field } }
109
+ : { type: 'in', field, values: [scalar(field, type, value)] };
110
+
111
+ const list = (field: string, type: FieldType, operator: string, value: unknown): VisibilityCondition => {
112
+ if (!Array.isArray(value)) {
113
+ return fail(field, `takes an array for ${operator}`);
114
+ }
115
+
116
+ return { type: 'in', field, values: value.map((item) => scalar(field, type, item)) };
117
+ };
118
+
119
+ const condition = (field: string, declaration: FieldDeclaration, value: unknown): VisibilityCondition => {
120
+ const { type } = declaration;
121
+ if (type === 'geo') {
122
+ return fail(field, "is a geo field, which a search visibility filter can't use");
123
+ }
124
+ if (!isPlainObject(value)) {
125
+ return equals(field, type, value);
126
+ }
127
+
128
+ const ordered = type === 'date' || type === 'number';
129
+ const clauses: VisibilityCondition[] = [];
130
+ const bounds: Extract<VisibilityCondition, { type: 'range' }>['bounds'] = {};
131
+ for (const [operator, operand] of Object.entries(value)) {
132
+ if (operand === undefined) {
133
+ continue;
134
+ }
135
+ if (ordered && (RANGE as readonly string[]).includes(operator)) {
136
+ bounds[operator as (typeof RANGE)[number]] = scalar(field, type, operand) as number | Date;
137
+ continue;
138
+ }
139
+ if (!EQUALITY.includes(operator)) {
140
+ return fail(field, `is a ${type} field, which can't take ${operator}`);
141
+ }
142
+
143
+ const positive =
144
+ operator === 'equals' || operator === 'not'
145
+ ? equals(field, type, operand)
146
+ : list(field, type, operator, operand);
147
+ clauses.push(operator === 'not' || operator === 'notIn' ? { type: 'not', clause: positive } : positive);
148
+ }
149
+ if (Object.keys(bounds).length > 0) {
150
+ clauses.push({ type: 'range', field, bounds });
151
+ }
152
+
153
+ return clauses.length === 1 ? clauses[0] : { type: 'and', clauses };
154
+ };
155
+
156
+ const check = (node: unknown, path: string): VisibilityCondition => {
157
+ if (!isPlainObject(node)) {
158
+ return fail(path, 'must be an object of field conditions');
159
+ }
160
+
161
+ const clauses: VisibilityCondition[] = [];
162
+ for (const [key, value] of Object.entries(node)) {
163
+ if (value === undefined) {
164
+ continue;
165
+ }
166
+
167
+ if ((COMBINATORS as readonly string[]).includes(key)) {
168
+ if (!Array.isArray(value)) {
169
+ return fail(key, 'takes an array of filters');
170
+ }
171
+ const nested = value.map((item, index) => check(item, `${key}[${index}]`));
172
+ clauses.push(
173
+ key === 'AND'
174
+ ? { type: 'and', clauses: nested }
175
+ : key === 'OR'
176
+ ? { type: 'or', clauses: nested }
177
+ : { type: 'not', clause: { type: 'or', clauses: nested } },
178
+ );
179
+ continue;
180
+ }
181
+
182
+ const declaration = Object.hasOwn(declarations, key) ? declarations[key] : undefined;
183
+ if (!declaration) {
184
+ return fail(key, "isn't a declared field");
185
+ }
186
+ clauses.push(condition(key, declaration, value));
187
+ }
188
+
189
+ return clauses.length === 1 ? clauses[0] : { type: 'and', clauses };
190
+ };
191
+
192
+ return check(where, 'filter');
193
+ };
@@ -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,78 @@
1
+ import { isAbsolute } 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
+ type DefaultKeys<Key> = {
40
+ metadata: (entity: Entity) => Key | null;
41
+ content: (file: File) => Key | null;
42
+ };
43
+
44
+ /**
45
+ * Find each item's key from `locate`, or else from `meta`, throwing through `check` on an unsafe one
46
+ */
47
+ export const locator = <Key>(
48
+ locate: StorageLocate<Key>,
49
+ defaults: DefaultKeys<Key>,
50
+ check: (key: Key, id: string) => unknown,
51
+ ) => {
52
+ const checked = (key: Key | null, id: string) => {
53
+ if (key !== null) {
54
+ check(key, id);
55
+ }
56
+
57
+ return key;
58
+ };
59
+
60
+ return {
61
+ metadata: async (entity: Entity) => checked(await (locate.metadata ?? defaults.metadata)(entity), entity.id),
62
+ content: async (file: File, entity: Entity) =>
63
+ checked(await (locate.content ?? defaults.content)(file, entity), file.id),
64
+ };
65
+ };
66
+
67
+ /**
68
+ * A `locator` for string keys read from the same `meta` key of `Meta` on entities and files
69
+ */
70
+ export const keyLocator = <Meta>(locate: StorageLocate, key: Extract<keyof Meta, string>) =>
71
+ locator(
72
+ locate,
73
+ {
74
+ metadata: (entity) => metaString<Meta>(entity.meta, entity.id, key),
75
+ content: (file) => metaString<Meta>(file.meta, file.id, key),
76
+ },
77
+ safeKey,
78
+ );
@@ -0,0 +1,71 @@
1
+ import { openStorageRoot } from '@ocfl/ocfl-fs';
2
+ import type { Entity, File } from '../../generated/prisma/client.js';
3
+ import type { OcflLocation, OcflStorageMeta, StorageBackend, StorageLocate, StreamDelivery } from '../backend.js';
4
+ import { locator, metaString, safeKey } from '../location.js';
5
+ import { nullIfMissing, withContentType } from '../results.js';
6
+
7
+ export type OcflStorageOptions = {
8
+ /** The OCFL storage root, whose ocfl_layout.json names a storage layout @ocfl/ocfl-fs implements */
9
+ root: string;
10
+ /** Where each item sits, instead of `meta.ocflObject` and `meta.ocflPath` */
11
+ locate?: StorageLocate<OcflLocation>;
12
+ };
13
+
14
+ const METADATA_PATH = 'ro-crate-metadata.json';
15
+
16
+ const MISSING: ReadonlySet<string> = new Set(['OBJECT_NOT_FOUND']);
17
+
18
+ const metaKey = (row: Entity | File, key: keyof OcflStorageMeta) => metaString<OcflStorageMeta>(row.meta, row.id, key);
19
+
20
+ const defaultLocations = {
21
+ metadata: (entity: Entity): OcflLocation | null => {
22
+ const object = metaKey(entity, 'ocflObject');
23
+ const path = metaKey(entity, 'ocflPath') ?? METADATA_PATH;
24
+
25
+ return object === null ? null : { object, path };
26
+ },
27
+ content: (file: File): OcflLocation | null => {
28
+ const object = metaKey(file, 'ocflObject');
29
+ const path = metaKey(file, 'ocflPath');
30
+
31
+ return object === null || path === null ? null : { object, path };
32
+ },
33
+ };
34
+
35
+ /** An object id is mapped by the layout, so only the logical path is a key */
36
+ const safeLocation = ({ path }: OcflLocation, id: string) => safeKey(path, id);
37
+
38
+ /**
39
+ * Serve Metadata and Content from the head version of objects in an OCFL storage root on local disk
40
+ * Throws an `OcflError` when `root` isn't a storage root, or uses a storage layout @ocfl/ocfl-fs doesn't implement
41
+ */
42
+ export const OcflStorage = async ({ root, locate = {} }: OcflStorageOptions): Promise<StorageBackend> => {
43
+ const storageRoot = await openStorageRoot(root);
44
+ const locations = locator(locate, defaultLocations, safeLocation);
45
+
46
+ const deliver = async (location: OcflLocation | null): Promise<StreamDelivery | null> => {
47
+ if (location === null) {
48
+ return null;
49
+ }
50
+
51
+ const object = await nullIfMissing(storageRoot.open(location.object), MISSING);
52
+ const file = object?.head.files.get(location.path);
53
+ if (!file) {
54
+ return null;
55
+ }
56
+
57
+ return {
58
+ type: 'stream',
59
+ open: () => file.stream(),
60
+ contentLength: await file.size(),
61
+ etag: `"${file.digest}"`,
62
+ lastModified: file.modifiedAt,
63
+ };
64
+ };
65
+
66
+ return {
67
+ metadata: async (entity) => deliver(await locations.metadata(entity)),
68
+ content: async (file, entity) =>
69
+ withContentType(await deliver(await locations.content(file, entity)), file.mediaType),
70
+ };
71
+ };
@@ -0,0 +1,32 @@
1
+ import type { Stats } from 'node:fs';
2
+ import type { PathDelivery } from './backend.js';
3
+
4
+ const FS_MISSING: ReadonlySet<string> = new Set(['ENOENT', 'ENOTDIR']);
5
+
6
+ /**
7
+ * Resolve to `null` when the error's code or name is in `missing`, else rethrow
8
+ */
9
+ export const nullIfMissing = async <T>(promise: Promise<T>, missing = FS_MISSING): Promise<T | null> => {
10
+ try {
11
+ return await promise;
12
+ } catch (error) {
13
+ const { code, name } = error as NodeJS.ErrnoException;
14
+ if (missing.has(String(code)) || missing.has(name)) {
15
+ return null;
16
+ }
17
+
18
+ throw error;
19
+ }
20
+ };
21
+
22
+ export const pathDelivery = (path: string, stats: Stats, etag: string): PathDelivery => ({
23
+ type: 'path',
24
+ path,
25
+ contentLength: stats.size,
26
+ etag,
27
+ lastModified: stats.mtime,
28
+ });
29
+
30
+ /** A Content delivery from a backend's shared one, typed by `File.mediaType` */
31
+ export const withContentType = <Delivery extends object>(delivery: Delivery | null, contentType: string) =>
32
+ delivery && { ...delivery, contentType };
@@ -0,0 +1,79 @@
1
+ import type { Readable } from 'node:stream';
2
+ import { GetObjectCommand, HeadObjectCommand, type S3Client } from '@aws-sdk/client-s3';
3
+ import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
4
+ import type { S3StorageMeta, StorageBackend, StorageLocate, StreamDelivery } from '../backend.js';
5
+ import { keyLocator } from '../location.js';
6
+ import { nullIfMissing, withContentType } from '../results.js';
7
+
8
+ export type S3StorageOptions = {
9
+ /** Your S3 client; arocapi never configures or destroys it */
10
+ client: S3Client;
11
+ bucket: string;
12
+ /** Where each item sits in the bucket, instead of `meta.storageKey` */
13
+ locate?: StorageLocate;
14
+ /** How Content reaches the client: a presigned URL (default), or proxied through arocapi. Metadata always streams */
15
+ delivery?: 'redirect' | 'stream';
16
+ /** Seconds a presigned URL stays valid */
17
+ expiresIn?: number;
18
+ };
19
+
20
+ const MISSING: ReadonlySet<string> = new Set(['NoSuchKey', 'NotFound']);
21
+
22
+ /**
23
+ * Serve Metadata and Content from an S3-compatible bucket, found from `Entity.meta.storageKey` and `File.meta.storageKey`
24
+ */
25
+ export const S3Storage = ({
26
+ client,
27
+ bucket,
28
+ locate = {},
29
+ delivery = 'redirect',
30
+ expiresIn = 300,
31
+ }: S3StorageOptions): StorageBackend => {
32
+ const keys = keyLocator<S3StorageMeta>(locate, 'storageKey');
33
+
34
+ const stream = async (key: string | null): Promise<StreamDelivery | null> => {
35
+ if (key === null) {
36
+ return null;
37
+ }
38
+
39
+ const head = await nullIfMissing(client.send(new HeadObjectCommand({ Bucket: bucket, Key: key })), MISSING);
40
+ if (!head) {
41
+ return null;
42
+ }
43
+
44
+ return {
45
+ type: 'stream',
46
+ contentLength: Number(head.ContentLength),
47
+ etag: head.ETag,
48
+ lastModified: head.LastModified,
49
+ // IfMatch keeps GET to the version HEAD described; a newer one fails the request
50
+ open: async () => {
51
+ const object = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key, IfMatch: head.ETag }));
52
+
53
+ return object.Body as Readable;
54
+ },
55
+ };
56
+ };
57
+
58
+ return {
59
+ metadata: async (entity) => stream(await keys.metadata(entity)),
60
+ content: async (file, entity, { contentDisposition }) => {
61
+ const Key = await keys.content(file, entity);
62
+ if (delivery === 'stream') {
63
+ return withContentType(await stream(Key), file.mediaType);
64
+ }
65
+ if (Key === null) {
66
+ return null;
67
+ }
68
+
69
+ const command = new GetObjectCommand({
70
+ Bucket: bucket,
71
+ Key,
72
+ ResponseContentType: file.mediaType,
73
+ ResponseContentDisposition: contentDisposition,
74
+ });
75
+
76
+ return { type: 'redirect', url: await getSignedUrl(client, command, { expiresIn }) };
77
+ },
78
+ };
79
+ };