arocapi 1.1.0 → 1.2.2
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.md +5 -0
- package/README.md +459 -36
- package/dist/app.d.ts +19 -1
- package/dist/app.js +37 -29
- package/dist/app.js.map +1 -1
- package/dist/app.test.js +124 -0
- package/dist/app.test.js.map +1 -0
- package/dist/index.dev.js +146 -0
- package/dist/index.dev.js.map +1 -0
- package/dist/routes/crate.d.ts +7 -0
- package/dist/routes/crate.js +101 -0
- package/dist/routes/crate.js.map +1 -0
- package/dist/routes/crate.test.d.ts +1 -0
- package/dist/routes/crate.test.js +360 -0
- package/dist/routes/crate.test.js.map +1 -0
- package/dist/routes/entities.d.ts +6 -1
- package/dist/routes/entities.js +52 -39
- package/dist/routes/entities.js.map +1 -1
- package/dist/routes/entities.test.d.ts +1 -0
- package/dist/routes/entities.test.js +245 -0
- package/dist/routes/entities.test.js.map +1 -0
- package/dist/routes/entity.d.ts +6 -1
- package/dist/routes/entity.js +30 -8
- package/dist/routes/entity.js.map +1 -1
- package/dist/routes/entity.test.d.ts +1 -0
- package/dist/routes/entity.test.js +109 -0
- package/dist/routes/entity.test.js.map +1 -0
- package/dist/routes/file.d.ts +7 -0
- package/dist/routes/file.js +113 -0
- package/dist/routes/file.js.map +1 -0
- package/dist/routes/file.test.d.ts +1 -0
- package/dist/routes/file.test.js +319 -0
- package/dist/routes/file.test.js.map +1 -0
- package/dist/routes/files.d.ts +8 -0
- package/dist/routes/files.js +62 -0
- package/dist/routes/files.js.map +1 -0
- package/dist/routes/files.test.d.ts +1 -0
- package/dist/routes/files.test.js +244 -0
- package/dist/routes/files.test.js.map +1 -0
- package/dist/routes/search.d.ts +6 -1
- package/dist/routes/search.js +44 -19
- package/dist/routes/search.js.map +1 -1
- package/dist/routes/search.test.d.ts +1 -0
- package/dist/routes/search.test.js +698 -0
- package/dist/routes/search.test.js.map +1 -0
- package/dist/test/helpers/fastify.d.ts +9 -0
- package/dist/test/helpers/fastify.js +24 -0
- package/dist/test/helpers/fastify.js.map +1 -0
- package/dist/test/integration.setup.d.ts +58 -0
- package/dist/test/integration.setup.js +181 -0
- package/dist/test/integration.setup.js.map +1 -0
- package/dist/test/integration.test.d.ts +1 -0
- package/dist/test/integration.test.js +337 -0
- package/dist/test/integration.test.js.map +1 -0
- package/dist/transformers/default.d.ts +45 -0
- package/dist/transformers/default.js +46 -0
- package/dist/transformers/default.js.map +1 -0
- package/dist/transformers/default.test.d.ts +1 -0
- package/dist/transformers/default.test.js +177 -0
- package/dist/transformers/default.test.js.map +1 -0
- package/dist/transformers/transformer.test.d.ts +1 -0
- package/dist/transformers/transformer.test.js +176 -0
- package/dist/transformers/transformer.test.js.map +1 -0
- package/dist/types/fileHandlers.d.ts +41 -0
- package/dist/types/fileHandlers.js +2 -0
- package/dist/types/fileHandlers.js.map +1 -0
- package/dist/types/transformers.d.ts +10 -0
- package/dist/types/transformers.js +2 -0
- package/dist/types/transformers.js.map +1 -0
- package/dist/utils/errors.d.ts +23 -0
- package/dist/utils/errors.js +21 -0
- package/dist/utils/errors.js.map +1 -0
- package/dist/utils/errors.test.d.ts +1 -0
- package/dist/utils/errors.test.js +66 -0
- package/dist/utils/errors.test.js.map +1 -0
- package/package.json +35 -28
- package/prisma/migrations/20250827033956_record_type_scalar/migration.sql +10 -0
- package/prisma/migrations/20250923032753_api_refactor/migration.sql +39 -0
- package/prisma/migrations/20250923223119_entity_type_to_string/migration.sql +8 -0
- package/prisma/migrations/20251020140329_add_meta_column/migration.sql +2 -0
- package/prisma/migrations/20251027010713_add_file_table/migration.sql +17 -0
- package/prisma/migrations/20251027221138_add_file_id_to_entity/migration.sql +2 -0
- package/prisma/models/entity.prisma +16 -12
- package/prisma/models/file.prisma +20 -0
- package/prisma.config.ts +6 -1
- package/src/__snapshots__/app.test.ts.snap +8 -0
- package/src/app.test.ts +158 -0
- package/src/app.ts +99 -36
- package/src/index.dev.ts +196 -0
- package/src/reset.d.ts +1 -0
- package/src/routes/__snapshots__/entities.test.ts.snap +68 -0
- package/src/routes/__snapshots__/entity.test.ts.snap +57 -0
- package/src/routes/__snapshots__/search.test.ts.snap +139 -0
- package/src/routes/crate.test.ts +441 -0
- package/src/routes/crate.ts +145 -0
- package/src/routes/entities.test.ts +284 -0
- package/src/routes/entities.ts +69 -48
- package/src/routes/entity.test.ts +132 -0
- package/src/routes/entity.ts +59 -22
- package/src/routes/file.test.ts +399 -0
- package/src/routes/file.ts +157 -0
- package/src/routes/files.test.ts +303 -0
- package/src/routes/files.ts +89 -0
- package/src/routes/search.test.ts +807 -0
- package/src/routes/search.ts +67 -25
- package/src/test/__snapshots__/integration.test.ts.snap +18 -0
- package/src/test/helpers/fastify.ts +39 -0
- package/src/test/integration.setup.ts +200 -0
- package/src/test/integration.test.ts +411 -0
- package/src/transformers/default.test.ts +199 -0
- package/src/transformers/default.ts +165 -0
- package/src/transformers/transformer.test.ts +233 -0
- package/src/types/fileHandlers.ts +65 -0
- package/src/types/transformers.ts +52 -0
- package/src/utils/errors.test.ts +75 -0
- package/src/utils/errors.ts +45 -0
- package/dist/index.js +0 -25
- package/dist/index.js.map +0 -1
- package/dist/scripts/loadEntities.js +0 -170
- package/dist/scripts/loadEntities.js.map +0 -1
- package/dist/type.d.ts +0 -6
- package/dist/type.js +0 -2
- package/dist/type.js.map +0 -1
- package/src/index.ts +0 -35
- package/src/scripts/loadEntities.ts +0 -223
- package/src/type.ts +0 -7
- /package/dist/{scripts/loadEntities.d.ts → app.test.d.ts} +0 -0
- /package/dist/{index.d.ts → index.dev.d.ts} +0 -0
package/LICENSE.md
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
Copyright 2025 TBA
|
|
2
|
+
|
|
3
|
+
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
|
|
4
|
+
|
|
5
|
+
THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
|
|
2
1
|
# An RO-Crate API for Data Collections : Arocapi
|
|
3
2
|
|
|
4
3
|
This project a prototype implementation of an RO-Crate based collections
|
|
@@ -73,11 +72,12 @@ OPENSEARCH_URL="http://localhost:9200"
|
|
|
73
72
|
Create your Fastify application with Typescript support:
|
|
74
73
|
|
|
75
74
|
```typescript
|
|
76
|
-
// src/
|
|
75
|
+
// src/index.ts
|
|
77
76
|
import { Client } from '@opensearch-project/opensearch';
|
|
78
|
-
import arocapi from 'arocapi';
|
|
79
|
-
import
|
|
77
|
+
import arocapi, { AllPublicAccessTransformer, AllPublicFileAccessTransformer } from 'arocapi';
|
|
78
|
+
import Fastify from 'fastify';
|
|
80
79
|
import { PrismaClient } from './generated/prisma/client.js';
|
|
80
|
+
import { Readable } from 'stream';
|
|
81
81
|
|
|
82
82
|
// NOTE: Only needed if you are going to use these yourself
|
|
83
83
|
declare module 'fastify' {
|
|
@@ -98,7 +98,43 @@ const opensearch = new Client({ node: opensearchUrl });
|
|
|
98
98
|
const fastify = Fastify({
|
|
99
99
|
logger: true,
|
|
100
100
|
});
|
|
101
|
-
|
|
101
|
+
|
|
102
|
+
// For fully public datasets
|
|
103
|
+
fastify.register(arocapi, {
|
|
104
|
+
prisma,
|
|
105
|
+
opensearch,
|
|
106
|
+
accessTransformer: AllPublicAccessTransformer,
|
|
107
|
+
fileAccessTransformer: AllPublicFileAccessTransformer,
|
|
108
|
+
// Required: File handler for serving File entity content
|
|
109
|
+
fileHandler: {
|
|
110
|
+
get: async (file) => {
|
|
111
|
+
const fileUrl = `https://storage.example.com/${file.meta.storagePath}`;
|
|
112
|
+
return { type: 'redirect', url: fileUrl };
|
|
113
|
+
},
|
|
114
|
+
head: async (file) => ({
|
|
115
|
+
contentType: file.mediaType,
|
|
116
|
+
contentLength: file.size,
|
|
117
|
+
}),
|
|
118
|
+
},
|
|
119
|
+
// Required: RO-Crate handler for serving RO-Crate metadata
|
|
120
|
+
roCrateHandler: {
|
|
121
|
+
get: async (entity) => {
|
|
122
|
+
const jsonString = JSON.stringify(entity.rocrate, null, 2);
|
|
123
|
+
return {
|
|
124
|
+
type: 'stream',
|
|
125
|
+
stream: Readable.from([jsonString]),
|
|
126
|
+
metadata: {
|
|
127
|
+
contentType: 'application/ld+json',
|
|
128
|
+
contentLength: Buffer.byteLength(jsonString),
|
|
129
|
+
},
|
|
130
|
+
};
|
|
131
|
+
},
|
|
132
|
+
head: async (entity) => ({
|
|
133
|
+
contentType: 'application/ld+json',
|
|
134
|
+
contentLength: Buffer.byteLength(JSON.stringify(entity.rocrate)),
|
|
135
|
+
}),
|
|
136
|
+
},
|
|
137
|
+
});
|
|
102
138
|
|
|
103
139
|
try {
|
|
104
140
|
await fastify.listen({ port: 3000 });
|
|
@@ -151,7 +187,7 @@ npx prisma init --datasource-provider mysql
|
|
|
151
187
|
|
|
152
188
|
### 2. Configure Prisma Multi-Model Setup
|
|
153
189
|
|
|
154
|
-
|
|
190
|
+
Modify the `prisma.config.ts` file in your project root to support folder based schemas:
|
|
155
191
|
|
|
156
192
|
```typescript
|
|
157
193
|
// prisma.config.ts
|
|
@@ -159,6 +195,7 @@ import 'dotenv/config';
|
|
|
159
195
|
import { defineConfig } from 'prisma/config';
|
|
160
196
|
|
|
161
197
|
export default defineConfig({
|
|
198
|
+
// Adds support for folder based schemas
|
|
162
199
|
schema: 'prisma',
|
|
163
200
|
});
|
|
164
201
|
```
|
|
@@ -172,54 +209,440 @@ Create the directory structure and link to arocapi models:
|
|
|
172
209
|
mkdir -p prisma/models
|
|
173
210
|
|
|
174
211
|
# Link to the upstream arocapi models
|
|
175
|
-
|
|
212
|
+
ln -s ../../node_modules/arocapi/prisma/models prisma/arocapi
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### 4. Generate Prisma Client and Run Migrations
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
# Create database migrations for this version of arocapi
|
|
219
|
+
npx prisma migrate dev --name="arocapi-$(pnpm list | grep arocapi | awk '{ print $2 }')"
|
|
220
|
+
|
|
221
|
+
# Generate the Prisma client
|
|
222
|
+
npx prisma generate
|
|
223
|
+
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## Available API Routes
|
|
227
|
+
|
|
228
|
+
The arocapi provides the following endpoints:
|
|
229
|
+
|
|
230
|
+
- `GET /entities` - List all entities with pagination and filtering
|
|
231
|
+
- `GET /entity/:id` - Get a specific entity by ID
|
|
232
|
+
- `GET /entity/:id/rocrate` - Download RO-Crate metadata
|
|
233
|
+
- `GET /files` - List files with pagination and filtering
|
|
234
|
+
- `GET /file/:id` - Download or access file content
|
|
235
|
+
- `POST /search` - Search entities using OpenSearch
|
|
236
|
+
|
|
237
|
+
## Customising Entity Responses
|
|
238
|
+
|
|
239
|
+
The API provides a flexible transformer system for customising entity responses
|
|
240
|
+
through two types of transformers:
|
|
241
|
+
|
|
242
|
+
### Access Transformer (Required)
|
|
243
|
+
|
|
244
|
+
The `accessTransformer` parameter is **required** for security. You must explicitly
|
|
245
|
+
choose how access control is handled for your repository.
|
|
246
|
+
|
|
247
|
+
**For fully public datasets**, use `AllPublicAccessTransformer`:
|
|
248
|
+
|
|
249
|
+
```typescript
|
|
250
|
+
import arocapi, { AllPublicAccessTransformer } from 'arocapi';
|
|
251
|
+
|
|
252
|
+
await server.register(arocapi, {
|
|
253
|
+
prisma,
|
|
254
|
+
opensearch,
|
|
255
|
+
accessTransformer: AllPublicAccessTransformer,
|
|
256
|
+
});
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
**For restricted content**, implement a custom access transformer:
|
|
260
|
+
|
|
261
|
+
```typescript
|
|
262
|
+
const accessTransformer = async (entity, { request, fastify }) => {
|
|
263
|
+
// Custom logic to determine access
|
|
264
|
+
const user = await authenticateUser(request);
|
|
265
|
+
const canAccessContent = await checkLicense(entity.contentLicenseId, user);
|
|
266
|
+
|
|
267
|
+
return {
|
|
268
|
+
...entity,
|
|
269
|
+
access: {
|
|
270
|
+
metadata: true, // Metadata always visible
|
|
271
|
+
content: canAccessContent,
|
|
272
|
+
contentAuthorisationUrl: canAccessContent
|
|
273
|
+
? undefined
|
|
274
|
+
: 'https://rems.example.com/request-access',
|
|
275
|
+
},
|
|
276
|
+
};
|
|
277
|
+
};
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
> [!WARNING]
|
|
281
|
+
> The `accessTransformer` is required to prevent accidental exposure of
|
|
282
|
+
> restricted content. You must make an explicit choice about access control for
|
|
283
|
+
> your repository.
|
|
284
|
+
|
|
285
|
+
### Entity Transformers
|
|
286
|
+
|
|
287
|
+
Optional transformations for enriching or modifying response data. Multiple
|
|
288
|
+
transformers can be chained together.
|
|
289
|
+
|
|
290
|
+
```typescript
|
|
291
|
+
await server.register(arocapi, {
|
|
292
|
+
prisma,
|
|
293
|
+
opensearch,
|
|
294
|
+
accessTransformer: AllPublicAccessTransformer,
|
|
295
|
+
entityTransformers: [
|
|
296
|
+
// Add computed fields
|
|
297
|
+
(entity) => ({
|
|
298
|
+
...entity,
|
|
299
|
+
displayName: `${entity.name} [${entity.entityType.split('/').pop()}]`,
|
|
300
|
+
}),
|
|
301
|
+
// Add counts
|
|
302
|
+
async (entity, { fastify }) => {
|
|
303
|
+
const objectCount = entity.memberOf
|
|
304
|
+
? await fastify.prisma.entity.count({
|
|
305
|
+
where: { memberOf: entity.rocrateId },
|
|
306
|
+
})
|
|
307
|
+
: 0;
|
|
308
|
+
|
|
309
|
+
return {
|
|
310
|
+
...entity,
|
|
311
|
+
counts: {
|
|
312
|
+
objects: objectCount,
|
|
313
|
+
}
|
|
314
|
+
};
|
|
315
|
+
},
|
|
316
|
+
],
|
|
317
|
+
});
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
### Transformation Pipeline
|
|
321
|
+
|
|
322
|
+
Every entity response flows through this three-stage pipeline:
|
|
323
|
+
|
|
324
|
+
1. **Base transformer** - Converts database entities to standard format
|
|
325
|
+
2. **Access transformer** - Adds access control information
|
|
326
|
+
3. **Entity transformers** - Optional additional transformations
|
|
327
|
+
|
|
328
|
+
### Common Use Cases
|
|
329
|
+
|
|
330
|
+
**Access control for restricted content:**
|
|
331
|
+
|
|
332
|
+
```typescript
|
|
333
|
+
accessTransformer: async (entity, { request, fastify }) => {
|
|
334
|
+
const hasAccess = await checkUserPermissions(request, entity.contentLicenseId);
|
|
335
|
+
return {
|
|
336
|
+
...entity,
|
|
337
|
+
access: {
|
|
338
|
+
metadata: true,
|
|
339
|
+
content: hasAccess,
|
|
340
|
+
},
|
|
341
|
+
};
|
|
342
|
+
}
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
**Adding computed or derived fields:**
|
|
346
|
+
|
|
347
|
+
```typescript
|
|
348
|
+
entityTransformers: [
|
|
349
|
+
(entity) => ({
|
|
350
|
+
...entity,
|
|
351
|
+
shortId: entity.id.split('/').pop(),
|
|
352
|
+
year: extractYear(entity.description),
|
|
353
|
+
}),
|
|
354
|
+
]
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
**Fetching related data asynchronously:**
|
|
358
|
+
|
|
359
|
+
```typescript
|
|
360
|
+
entityTransformers: [
|
|
361
|
+
async (entity, { fastify }) => ({
|
|
362
|
+
...entity,
|
|
363
|
+
stats: await fetchEntityStats(entity.id, fastify.prisma),
|
|
364
|
+
}),
|
|
365
|
+
]
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
## Customising File Responses
|
|
369
|
+
|
|
370
|
+
The API provides a separate transformer system for file responses, similar to entity transformers but specifically designed for files.
|
|
371
|
+
|
|
372
|
+
### File Access Transformer (Required)
|
|
373
|
+
|
|
374
|
+
The `fileAccessTransformer` parameter is **required** for security. You must explicitly choose how access control is handled for file content.
|
|
375
|
+
|
|
376
|
+
**Key Difference from Entity Transformers**: File metadata (filename, size, mediaType, etc.) is always accessible. Only content access is controlled via the `access.content` field.
|
|
377
|
+
|
|
378
|
+
**For fully public datasets**, use `AllPublicFileAccessTransformer`:
|
|
379
|
+
|
|
380
|
+
```typescript
|
|
381
|
+
import arocapi, { AllPublicAccessTransformer, AllPublicFileAccessTransformer } from 'arocapi';
|
|
382
|
+
|
|
383
|
+
await server.register(arocapi, {
|
|
384
|
+
prisma,
|
|
385
|
+
opensearch,
|
|
386
|
+
accessTransformer: AllPublicAccessTransformer,
|
|
387
|
+
fileAccessTransformer: AllPublicFileAccessTransformer,
|
|
388
|
+
});
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
**For restricted content**, implement a custom file access transformer:
|
|
392
|
+
|
|
393
|
+
```typescript
|
|
394
|
+
const fileAccessTransformer = async (file, { request, fastify }) => {
|
|
395
|
+
// Custom logic to determine file content access
|
|
396
|
+
const user = await authenticateUser(request);
|
|
397
|
+
const canAccessContent = await checkLicense(file.contentLicenseId, user);
|
|
398
|
+
|
|
399
|
+
return {
|
|
400
|
+
...file,
|
|
401
|
+
access: {
|
|
402
|
+
content: canAccessContent,
|
|
403
|
+
contentAuthorizationUrl: canAccessContent
|
|
404
|
+
? undefined
|
|
405
|
+
: 'https://rems.example.com/request-access',
|
|
406
|
+
},
|
|
407
|
+
};
|
|
408
|
+
};
|
|
409
|
+
|
|
410
|
+
await server.register(arocapi, {
|
|
411
|
+
prisma,
|
|
412
|
+
opensearch,
|
|
413
|
+
accessTransformer: AllPublicAccessTransformer,
|
|
414
|
+
fileAccessTransformer,
|
|
415
|
+
});
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
> [!WARNING]
|
|
419
|
+
> The `fileAccessTransformer` is required to prevent accidental exposure of
|
|
420
|
+
> restricted file content. You must make an explicit choice about access control
|
|
421
|
+
> for your files.
|
|
422
|
+
|
|
423
|
+
### File Transformers
|
|
424
|
+
|
|
425
|
+
Optional transformations for enriching or modifying file response data. Multiple
|
|
426
|
+
file transformers can be chained together.
|
|
427
|
+
|
|
428
|
+
```typescript
|
|
429
|
+
await server.register(arocapi, {
|
|
430
|
+
prisma,
|
|
431
|
+
opensearch,
|
|
432
|
+
accessTransformer: AllPublicAccessTransformer,
|
|
433
|
+
fileAccessTransformer: AllPublicFileAccessTransformer,
|
|
434
|
+
fileTransformers: [
|
|
435
|
+
// Add computed fields
|
|
436
|
+
(file) => ({
|
|
437
|
+
...file,
|
|
438
|
+
displayFilename: file.filename.toUpperCase(),
|
|
439
|
+
sizeInKB: Math.round(file.size / 1024),
|
|
440
|
+
extension: file.filename.split('.').pop(),
|
|
441
|
+
}),
|
|
442
|
+
// Fetch parent entity information
|
|
443
|
+
async (file, { fastify }) => {
|
|
444
|
+
const parent = await fastify.prisma.entity.findFirst({
|
|
445
|
+
where: { rocrateId: file.memberOf },
|
|
446
|
+
});
|
|
447
|
+
|
|
448
|
+
return {
|
|
449
|
+
...file,
|
|
450
|
+
parentEntity: parent ? {
|
|
451
|
+
id: parent.rocrateId,
|
|
452
|
+
name: parent.name,
|
|
453
|
+
type: parent.entityType,
|
|
454
|
+
} : null,
|
|
455
|
+
};
|
|
456
|
+
},
|
|
457
|
+
],
|
|
458
|
+
});
|
|
176
459
|
```
|
|
177
460
|
|
|
178
|
-
###
|
|
461
|
+
### File Transformation Pipeline
|
|
462
|
+
|
|
463
|
+
Every file response flows through this three-stage pipeline:
|
|
464
|
+
|
|
465
|
+
1. **Base file transformer** - Converts database File records to standard format
|
|
466
|
+
2. **File access transformer** - Adds access control information (content only)
|
|
467
|
+
3. **File transformers** - Optional additional transformations
|
|
468
|
+
|
|
469
|
+
### Applied Routes
|
|
470
|
+
|
|
471
|
+
File transformers are applied to the files listing route:
|
|
472
|
+
|
|
473
|
+
- `GET /files` - File list (each file transformed)
|
|
474
|
+
|
|
475
|
+
**Note**: The `/file/:id` endpoint (for downloading file content) uses the `fileHandler` system, not file transformers. See the File Handler System section below for details.
|
|
476
|
+
|
|
477
|
+
## File Handler System
|
|
478
|
+
|
|
479
|
+
The API provides two separate handler systems for serving different types of content. These are distinct from the file transformer system described above.
|
|
480
|
+
|
|
481
|
+
**Important Distinction:**
|
|
482
|
+
|
|
483
|
+
- **File Transformers** (above) - Transform file metadata in the `/files` listing endpoint response
|
|
484
|
+
- **File Handler** (this section) - Serves actual file content via the `/file/:id` download endpoint
|
|
485
|
+
- **RO-Crate Handler** (this section) - Serves RO-Crate metadata via the `/entity/:id/rocrate` endpoint
|
|
486
|
+
|
|
487
|
+
### File Handler (Required)
|
|
488
|
+
|
|
489
|
+
The `fileHandler` parameter is **required**. It serves actual file content for the `/file/:id` endpoint.
|
|
490
|
+
|
|
491
|
+
This handler is responsible for:
|
|
492
|
+
|
|
493
|
+
- Streaming file content from your storage backend
|
|
494
|
+
- Generating redirect URLs to external storage (S3, CDN, etc.)
|
|
495
|
+
- Implementing access control for file downloads
|
|
496
|
+
- Supporting HTTP range requests for media streaming
|
|
497
|
+
|
|
498
|
+
### RO-Crate Handler (Required)
|
|
179
499
|
|
|
180
|
-
|
|
500
|
+
The `roCrateHandler` parameter is **required**. It serves RO-Crate metadata as JSON-LD
|
|
501
|
+
for any entity type (Collection, Object, or File) via the `/entity/:id/rocrate` endpoint.
|
|
181
502
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
503
|
+
**File Handler Example** (S3 with redirect):
|
|
504
|
+
|
|
505
|
+
```typescript
|
|
506
|
+
fileHandler: {
|
|
507
|
+
get: async (file) => {
|
|
508
|
+
const command = new GetObjectCommand({
|
|
509
|
+
Bucket: file.meta.bucket,
|
|
510
|
+
Key: file.meta.s3Key,
|
|
511
|
+
});
|
|
512
|
+
const url = await getSignedUrl(s3, command, { expiresIn: 3600 });
|
|
513
|
+
|
|
514
|
+
return { type: 'redirect', url };
|
|
515
|
+
},
|
|
516
|
+
head: async (file) => {
|
|
517
|
+
return {
|
|
518
|
+
contentType: file.mediaType,
|
|
519
|
+
contentLength: file.size,
|
|
520
|
+
};
|
|
521
|
+
},
|
|
188
522
|
}
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
**File Handler Example** (local filesystem):
|
|
189
526
|
|
|
190
|
-
|
|
191
|
-
|
|
527
|
+
```typescript
|
|
528
|
+
fileHandler: {
|
|
529
|
+
get: async (file) => {
|
|
530
|
+
const filePath = `/data/files/${file.meta.storagePath}`;
|
|
531
|
+
const stats = await stat(filePath);
|
|
532
|
+
|
|
533
|
+
return {
|
|
534
|
+
type: 'stream',
|
|
535
|
+
stream: createReadStream(filePath),
|
|
536
|
+
metadata: {
|
|
537
|
+
contentType: file.mediaType,
|
|
538
|
+
contentLength: stats.size,
|
|
539
|
+
lastModified: stats.mtime,
|
|
540
|
+
},
|
|
541
|
+
};
|
|
542
|
+
},
|
|
543
|
+
head: async (file) => {
|
|
544
|
+
const filePath = `/data/files/${file.meta.storagePath}`;
|
|
545
|
+
const stats = await stat(filePath);
|
|
546
|
+
|
|
547
|
+
return {
|
|
548
|
+
contentType: file.mediaType,
|
|
549
|
+
contentLength: stats.size,
|
|
550
|
+
lastModified: stats.mtime,
|
|
551
|
+
};
|
|
552
|
+
},
|
|
192
553
|
}
|
|
554
|
+
```
|
|
193
555
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
556
|
+
**RO-Crate Handler Example** (stream from database):
|
|
557
|
+
|
|
558
|
+
```typescript
|
|
559
|
+
roCrateHandler: {
|
|
560
|
+
get: async (entity) => {
|
|
561
|
+
const jsonString = JSON.stringify(entity.rocrate, null, 2);
|
|
562
|
+
|
|
563
|
+
return {
|
|
564
|
+
type: 'stream',
|
|
565
|
+
stream: Readable.from([jsonString]),
|
|
566
|
+
metadata: {
|
|
567
|
+
contentType: 'application/ld+json',
|
|
568
|
+
contentLength: Buffer.byteLength(jsonString),
|
|
569
|
+
},
|
|
570
|
+
};
|
|
571
|
+
},
|
|
572
|
+
head: async (entity) => {
|
|
573
|
+
const jsonString = JSON.stringify(entity.rocrate);
|
|
574
|
+
return {
|
|
575
|
+
contentType: 'application/ld+json',
|
|
576
|
+
contentLength: Buffer.byteLength(jsonString),
|
|
577
|
+
};
|
|
578
|
+
},
|
|
197
579
|
}
|
|
198
580
|
```
|
|
199
581
|
|
|
200
|
-
###
|
|
582
|
+
### File Handler Response Types
|
|
201
583
|
|
|
202
|
-
|
|
203
|
-
# Generate the Prisma client
|
|
204
|
-
npx prisma generate
|
|
584
|
+
The file handler must return one of two response types:
|
|
205
585
|
|
|
206
|
-
|
|
207
|
-
npx prisma migrate deploy
|
|
586
|
+
**Redirect Response** - Redirect to external file location:
|
|
208
587
|
|
|
209
|
-
|
|
210
|
-
|
|
588
|
+
```typescript
|
|
589
|
+
{ type: 'redirect', url: 'https://storage.example.com/file.wav' }
|
|
211
590
|
```
|
|
212
591
|
|
|
213
|
-
|
|
592
|
+
**Stream Response** - Serve file content directly:
|
|
214
593
|
|
|
215
|
-
|
|
594
|
+
```typescript
|
|
595
|
+
{
|
|
596
|
+
type: 'stream',
|
|
597
|
+
stream: Readable, // Node.js readable stream
|
|
598
|
+
metadata: {
|
|
599
|
+
contentType: 'audio/wav',
|
|
600
|
+
contentLength: 1024,
|
|
601
|
+
etag?: '"abc123"', // Optional
|
|
602
|
+
lastModified?: new Date(), // Optional
|
|
603
|
+
},
|
|
604
|
+
}
|
|
605
|
+
```
|
|
216
606
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
- `
|
|
222
|
-
- `
|
|
607
|
+
### Query Parameters
|
|
608
|
+
|
|
609
|
+
The `/file/:id` endpoint supports these query parameters:
|
|
610
|
+
|
|
611
|
+
- `disposition` - 'inline' (default) or 'attachment' for download prompts
|
|
612
|
+
- `filename` - Custom filename for Content-Disposition header (defaults to entity.name)
|
|
613
|
+
- `noRedirect` - If true with redirect response, returns JSON `{location: url}` instead of HTTP 302
|
|
614
|
+
|
|
615
|
+
### HTTP Range Support
|
|
616
|
+
|
|
617
|
+
The endpoint automatically handles HTTP range requests for partial content,
|
|
618
|
+
useful for media streaming:
|
|
619
|
+
|
|
620
|
+
- Returns **206 Partial Content** for valid range requests
|
|
621
|
+
- Returns **416 Range Not Satisfiable** for invalid ranges
|
|
622
|
+
- Sets appropriate `Content-Range` and `Accept-Ranges` headers
|
|
623
|
+
|
|
624
|
+
### Entity Meta Field
|
|
625
|
+
|
|
626
|
+
The `meta` JSON field in the Entity model stores implementation-specific
|
|
627
|
+
metadata for your file handler:
|
|
628
|
+
|
|
629
|
+
```typescript
|
|
630
|
+
await prisma.entity.create({
|
|
631
|
+
data: {
|
|
632
|
+
rocrateId: 'http://example.com/file/123',
|
|
633
|
+
name: 'audio.wav',
|
|
634
|
+
entityType: 'http://schema.org/MediaObject',
|
|
635
|
+
// ... other required fields
|
|
636
|
+
meta: {
|
|
637
|
+
bucket: 's3://my-bucket',
|
|
638
|
+
storagePath: 'collections/col-01',
|
|
639
|
+
checksum: 'sha256:abc123...',
|
|
640
|
+
},
|
|
641
|
+
},
|
|
642
|
+
});
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
Your file handler can use this metadata to locate files in your storage system.
|
|
223
646
|
|
|
224
647
|
## Development Workflow
|
|
225
648
|
|
package/dist/app.d.ts
CHANGED
|
@@ -1,10 +1,28 @@
|
|
|
1
1
|
import type { Client } from '@opensearch-project/opensearch';
|
|
2
|
-
import type { PrismaClient } from '@prisma/client/extension';
|
|
3
2
|
import type { FastifyPluginAsync } from 'fastify';
|
|
3
|
+
import type { PrismaClient } from './generated/prisma/client.js';
|
|
4
|
+
import type { FileHandler, RoCrateHandler } from './types/fileHandlers.js';
|
|
5
|
+
import type { AccessTransformer, EntityTransformer, FileAccessTransformer, FileTransformer } from './types/transformers.js';
|
|
6
|
+
export type { AuthorisedEntity, AuthorisedFile, StandardEntity, StandardFile } from './transformers/default.js';
|
|
7
|
+
export { AllPublicAccessTransformer, AllPublicFileAccessTransformer } from './transformers/default.js';
|
|
8
|
+
export type { FileHandler, FileHandlerContext, FileMetadata, FilePathResult, FileRedirectResult, FileResult, FileStreamResult, GetFileHandler, GetRoCrateHandler, HeadFileHandler, HeadRoCrateHandler, RoCrateHandler, } from './types/fileHandlers.js';
|
|
9
|
+
export type { AccessTransformer, EntityTransformer, FileAccessTransformer, FileTransformer, TransformerContext, } from './types/transformers.js';
|
|
10
|
+
declare module 'fastify' {
|
|
11
|
+
interface FastifyInstance {
|
|
12
|
+
prisma: PrismaClient;
|
|
13
|
+
opensearch: Client;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
4
16
|
export type Options = {
|
|
5
17
|
prisma: PrismaClient;
|
|
6
18
|
opensearch: Client;
|
|
7
19
|
disableCors?: boolean;
|
|
20
|
+
accessTransformer: AccessTransformer;
|
|
21
|
+
entityTransformers?: EntityTransformer[];
|
|
22
|
+
fileAccessTransformer: FileAccessTransformer;
|
|
23
|
+
fileTransformers?: FileTransformer[];
|
|
24
|
+
fileHandler: FileHandler;
|
|
25
|
+
roCrateHandler: RoCrateHandler;
|
|
8
26
|
};
|
|
9
27
|
declare const _default: FastifyPluginAsync<Options>;
|
|
10
28
|
export default _default;
|
package/dist/app.js
CHANGED
|
@@ -1,36 +1,23 @@
|
|
|
1
1
|
import cors from '@fastify/cors';
|
|
2
2
|
import sensible from '@fastify/sensible';
|
|
3
3
|
import fp from 'fastify-plugin';
|
|
4
|
-
import { hasZodFastifySchemaValidationErrors,
|
|
4
|
+
import { hasZodFastifySchemaValidationErrors, serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
|
|
5
|
+
import crate from './routes/crate.js';
|
|
5
6
|
import entities from './routes/entities.js';
|
|
6
7
|
import entity from './routes/entity.js';
|
|
8
|
+
import file from './routes/file.js';
|
|
9
|
+
import files from './routes/files.js';
|
|
7
10
|
import search from './routes/search.js';
|
|
11
|
+
import { createValidationError } from './utils/errors.js';
|
|
12
|
+
export { AllPublicAccessTransformer, AllPublicFileAccessTransformer } from './transformers/default.js';
|
|
8
13
|
const setupValidation = (fastify) => {
|
|
9
14
|
fastify.setValidatorCompiler(validatorCompiler);
|
|
10
15
|
fastify.setSerializerCompiler(serializerCompiler);
|
|
11
|
-
fastify.setErrorHandler((
|
|
12
|
-
if (hasZodFastifySchemaValidationErrors(
|
|
13
|
-
return reply.code(400).send(
|
|
14
|
-
error: 'Response Validation Error',
|
|
15
|
-
message: "Request doesn't match the schema",
|
|
16
|
-
details: {
|
|
17
|
-
issues: err.validation,
|
|
18
|
-
method: req.method,
|
|
19
|
-
url: req.url,
|
|
20
|
-
},
|
|
21
|
-
});
|
|
22
|
-
}
|
|
23
|
-
if (isResponseSerializationError(err)) {
|
|
24
|
-
return reply.code(500).send({
|
|
25
|
-
error: 'Internal Server Error',
|
|
26
|
-
message: "Response doesn't match the schema",
|
|
27
|
-
details: {
|
|
28
|
-
issues: err.cause.issues,
|
|
29
|
-
method: err.method,
|
|
30
|
-
url: err.url,
|
|
31
|
-
},
|
|
32
|
-
});
|
|
16
|
+
fastify.setErrorHandler((error, _req, reply) => {
|
|
17
|
+
if (hasZodFastifySchemaValidationErrors(error)) {
|
|
18
|
+
return reply.code(400).send(createValidationError('The request parameters are invalid', error.validation));
|
|
33
19
|
}
|
|
20
|
+
const err = error;
|
|
34
21
|
return reply.code(500).send({
|
|
35
22
|
error: 'Internal Server Error',
|
|
36
23
|
message: err.message,
|
|
@@ -40,8 +27,8 @@ const setupValidation = (fastify) => {
|
|
|
40
27
|
const setupDatabase = async (fastify, prisma) => {
|
|
41
28
|
await prisma.$connect();
|
|
42
29
|
fastify.decorate('prisma', prisma);
|
|
43
|
-
fastify.addHook('onClose', async (
|
|
44
|
-
await
|
|
30
|
+
fastify.addHook('onClose', async () => {
|
|
31
|
+
await prisma.$disconnect();
|
|
45
32
|
});
|
|
46
33
|
};
|
|
47
34
|
const setupSearch = async (fastify, opensearch) => {
|
|
@@ -57,7 +44,25 @@ const setupSearch = async (fastify, opensearch) => {
|
|
|
57
44
|
fastify.addHook('onClose', () => opensearch.close());
|
|
58
45
|
};
|
|
59
46
|
const app = async (fastify, options) => {
|
|
60
|
-
const { prisma, opensearch, disableCors = false } = options
|
|
47
|
+
const { prisma, opensearch, disableCors = false, accessTransformer, entityTransformers, fileAccessTransformer, fileTransformers, fileHandler, roCrateHandler, } = options;
|
|
48
|
+
if (!prisma) {
|
|
49
|
+
throw new Error('Prisma client is required');
|
|
50
|
+
}
|
|
51
|
+
if (!opensearch) {
|
|
52
|
+
throw new Error('OpenSearch client is required');
|
|
53
|
+
}
|
|
54
|
+
if (!accessTransformer) {
|
|
55
|
+
throw new Error('accessTransformer is required');
|
|
56
|
+
}
|
|
57
|
+
if (!fileAccessTransformer) {
|
|
58
|
+
throw new Error('fileAccessTransformer is required');
|
|
59
|
+
}
|
|
60
|
+
if (!fileHandler) {
|
|
61
|
+
throw new Error('fileHandler is required');
|
|
62
|
+
}
|
|
63
|
+
if (!roCrateHandler) {
|
|
64
|
+
throw new Error('roCrateHandler is required');
|
|
65
|
+
}
|
|
61
66
|
fastify.register(sensible);
|
|
62
67
|
if (!disableCors) {
|
|
63
68
|
fastify.register(cors);
|
|
@@ -65,9 +70,12 @@ const app = async (fastify, options) => {
|
|
|
65
70
|
setupValidation(fastify);
|
|
66
71
|
await setupDatabase(fastify, prisma);
|
|
67
72
|
await setupSearch(fastify, opensearch);
|
|
68
|
-
fastify.register(entities);
|
|
69
|
-
fastify.register(entity);
|
|
70
|
-
fastify.register(
|
|
73
|
+
fastify.register(entities, { accessTransformer, entityTransformers });
|
|
74
|
+
fastify.register(entity, { accessTransformer, entityTransformers });
|
|
75
|
+
fastify.register(files, { fileAccessTransformer, fileTransformers });
|
|
76
|
+
fastify.register(file, { fileHandler });
|
|
77
|
+
fastify.register(crate, { roCrateHandler });
|
|
78
|
+
fastify.register(search, { accessTransformer, entityTransformers });
|
|
71
79
|
};
|
|
72
80
|
export default fp(app);
|
|
73
81
|
//# sourceMappingURL=app.js.map
|