arocapi 1.0.5 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/README.md +597 -29
  2. package/dist/app.d.ts +27 -6
  3. package/dist/app.js +76 -17
  4. package/dist/app.js.map +1 -1
  5. package/dist/app.test.js +124 -0
  6. package/dist/app.test.js.map +1 -0
  7. package/dist/express.d.ts +3 -2
  8. package/dist/express.js +11 -11
  9. package/dist/express.js.map +1 -1
  10. package/dist/index.dev.d.ts +8 -0
  11. package/dist/index.dev.js +146 -0
  12. package/dist/index.dev.js.map +1 -0
  13. package/dist/routes/crate.d.ts +7 -0
  14. package/dist/routes/crate.js +99 -0
  15. package/dist/routes/crate.js.map +1 -0
  16. package/dist/routes/crate.test.d.ts +1 -0
  17. package/dist/routes/crate.test.js +360 -0
  18. package/dist/routes/crate.test.js.map +1 -0
  19. package/dist/routes/entities.d.ts +8 -0
  20. package/dist/routes/entities.js +75 -0
  21. package/dist/routes/entities.js.map +1 -0
  22. package/dist/routes/entities.test.d.ts +1 -0
  23. package/dist/routes/entities.test.js +245 -0
  24. package/dist/routes/entities.test.js.map +1 -0
  25. package/dist/routes/entity.d.ts +8 -0
  26. package/dist/routes/entity.js +45 -0
  27. package/dist/routes/entity.js.map +1 -0
  28. package/dist/routes/entity.test.d.ts +1 -0
  29. package/dist/routes/entity.test.js +109 -0
  30. package/dist/routes/entity.test.js.map +1 -0
  31. package/dist/routes/file.d.ts +7 -0
  32. package/dist/routes/file.js +111 -0
  33. package/dist/routes/file.js.map +1 -0
  34. package/dist/routes/file.test.d.ts +1 -0
  35. package/dist/routes/file.test.js +319 -0
  36. package/dist/routes/file.test.js.map +1 -0
  37. package/dist/routes/files.d.ts +8 -0
  38. package/dist/routes/files.js +61 -0
  39. package/dist/routes/files.js.map +1 -0
  40. package/dist/routes/files.test.d.ts +1 -0
  41. package/dist/routes/files.test.js +244 -0
  42. package/dist/routes/files.test.js.map +1 -0
  43. package/dist/routes/search.d.ts +8 -0
  44. package/dist/routes/{search/index.js → search.js} +45 -19
  45. package/dist/routes/search.js.map +1 -0
  46. package/dist/routes/search.test.d.ts +1 -0
  47. package/dist/routes/search.test.js +698 -0
  48. package/dist/routes/search.test.js.map +1 -0
  49. package/dist/test/helpers/fastify.d.ts +9 -0
  50. package/dist/test/helpers/fastify.js +24 -0
  51. package/dist/test/helpers/fastify.js.map +1 -0
  52. package/dist/test/integration.setup.d.ts +58 -0
  53. package/dist/test/integration.setup.js +181 -0
  54. package/dist/test/integration.setup.js.map +1 -0
  55. package/dist/test/integration.test.d.ts +1 -0
  56. package/dist/test/integration.test.js +337 -0
  57. package/dist/test/integration.test.js.map +1 -0
  58. package/dist/transformers/default.d.ts +45 -0
  59. package/dist/transformers/default.js +46 -0
  60. package/dist/transformers/default.js.map +1 -0
  61. package/dist/transformers/default.test.d.ts +1 -0
  62. package/dist/transformers/default.test.js +177 -0
  63. package/dist/transformers/default.test.js.map +1 -0
  64. package/dist/transformers/transformer.test.d.ts +1 -0
  65. package/dist/transformers/transformer.test.js +176 -0
  66. package/dist/transformers/transformer.test.js.map +1 -0
  67. package/dist/types/fileHandlers.d.ts +41 -0
  68. package/dist/types/fileHandlers.js +2 -0
  69. package/dist/types/fileHandlers.js.map +1 -0
  70. package/dist/types/transformers.d.ts +10 -0
  71. package/dist/types/transformers.js +2 -0
  72. package/dist/types/transformers.js.map +1 -0
  73. package/dist/utils/errors.d.ts +23 -0
  74. package/dist/utils/errors.js +21 -0
  75. package/dist/utils/errors.js.map +1 -0
  76. package/dist/utils/errors.test.d.ts +1 -0
  77. package/dist/utils/errors.test.js +66 -0
  78. package/dist/utils/errors.test.js.map +1 -0
  79. package/package.json +34 -25
  80. package/prisma/migrations/20250827033956_record_type_scalar/migration.sql +10 -0
  81. package/prisma/migrations/20250923032753_api_refactor/migration.sql +39 -0
  82. package/prisma/migrations/20250923223119_entity_type_to_string/migration.sql +8 -0
  83. package/prisma/migrations/20251020140329_add_meta_column/migration.sql +2 -0
  84. package/prisma/migrations/20251027010713_add_file_table/migration.sql +17 -0
  85. package/prisma/migrations/20251027221138_add_file_id_to_entity/migration.sql +2 -0
  86. package/prisma/models/entity.prisma +16 -12
  87. package/prisma/models/file.prisma +20 -0
  88. package/prisma/schema.prisma +1 -20
  89. package/prisma.config.ts +6 -7
  90. package/src/__snapshots__/app.test.ts.snap +8 -0
  91. package/src/app.test.ts +158 -0
  92. package/src/app.ts +150 -30
  93. package/src/express.ts +12 -11
  94. package/src/index.dev.ts +196 -0
  95. package/src/reset.d.ts +1 -0
  96. package/src/routes/__snapshots__/entities.test.ts.snap +68 -0
  97. package/src/routes/__snapshots__/entity.test.ts.snap +66 -0
  98. package/src/routes/__snapshots__/search.test.ts.snap +139 -0
  99. package/src/routes/crate.test.ts +441 -0
  100. package/src/routes/crate.ts +141 -0
  101. package/src/routes/entities.test.ts +284 -0
  102. package/src/routes/entities.ts +101 -0
  103. package/src/routes/entity.test.ts +132 -0
  104. package/src/routes/entity.ts +63 -0
  105. package/src/routes/file.test.ts +399 -0
  106. package/src/routes/file.ts +153 -0
  107. package/src/routes/files.test.ts +303 -0
  108. package/src/routes/files.ts +87 -0
  109. package/src/routes/search.test.ts +807 -0
  110. package/src/routes/{search/index.ts → search.ts} +67 -24
  111. package/src/test/__snapshots__/integration.test.ts.snap +18 -0
  112. package/src/test/helpers/fastify.ts +39 -0
  113. package/src/test/integration.setup.ts +200 -0
  114. package/src/test/integration.test.ts +411 -0
  115. package/src/transformers/default.test.ts +199 -0
  116. package/src/transformers/default.ts +165 -0
  117. package/src/transformers/transformer.test.ts +233 -0
  118. package/src/types/fileHandlers.ts +65 -0
  119. package/src/types/transformers.ts +52 -0
  120. package/src/utils/errors.test.ts +75 -0
  121. package/src/utils/errors.ts +45 -0
  122. package/dist/plugins/cors.d.ts +0 -3
  123. package/dist/plugins/cors.js +0 -6
  124. package/dist/plugins/cors.js.map +0 -1
  125. package/dist/plugins/opensearch.d.ts +0 -9
  126. package/dist/plugins/opensearch.js +0 -22
  127. package/dist/plugins/opensearch.js.map +0 -1
  128. package/dist/plugins/prisma.d.ts +0 -8
  129. package/dist/plugins/prisma.js +0 -11
  130. package/dist/plugins/prisma.js.map +0 -1
  131. package/dist/plugins/sensible.d.ts +0 -3
  132. package/dist/plugins/sensible.js +0 -6
  133. package/dist/plugins/sensible.js.map +0 -1
  134. package/dist/plugins/support.d.ts +0 -9
  135. package/dist/plugins/support.js +0 -5
  136. package/dist/plugins/support.js.map +0 -1
  137. package/dist/plugins/validation.d.ts +0 -3
  138. package/dist/plugins/validation.js +0 -32
  139. package/dist/plugins/validation.js.map +0 -1
  140. package/dist/routes/entities/index.d.ts +0 -3
  141. package/dist/routes/entities/index.js +0 -63
  142. package/dist/routes/entities/index.js.map +0 -1
  143. package/dist/routes/entity/index.d.ts +0 -3
  144. package/dist/routes/entity/index.js +0 -24
  145. package/dist/routes/entity/index.js.map +0 -1
  146. package/dist/routes/search/index.d.ts +0 -3
  147. package/dist/routes/search/index.js.map +0 -1
  148. package/dist/scripts/loadEntities.js +0 -170
  149. package/dist/scripts/loadEntities.js.map +0 -1
  150. package/dist/type.d.ts +0 -6
  151. package/dist/type.js +0 -2
  152. package/dist/type.js.map +0 -1
  153. package/src/plugins/README.md +0 -16
  154. package/src/plugins/cors.ts +0 -11
  155. package/src/plugins/opensearch.ts +0 -32
  156. package/src/plugins/prisma.ts +0 -23
  157. package/src/plugins/sensible.ts +0 -11
  158. package/src/plugins/support.ts +0 -20
  159. package/src/plugins/validation.ts +0 -48
  160. package/src/routes/README.md +0 -29
  161. package/src/routes/entities/index.ts +0 -83
  162. package/src/routes/entity/index.ts +0 -28
  163. package/src/scripts/loadEntities.ts +0 -223
  164. package/src/type.ts +0 -7
  165. /package/dist/{scripts/loadEntities.d.ts → app.test.d.ts} +0 -0
package/README.md CHANGED
@@ -1,58 +1,628 @@
1
1
 
2
2
  # An RO-Crate API for Data Collections : Arocapi
3
3
 
4
- This project is a prototype implementation of an RO-Crate based collections archive and data portal based on the Portland Common Data model of collections suitable use in long-term archival repository systems that aim to follow the Protocols for Long Term Archival Repository Services ([PILARS]) <https://w3id.org/ldac/pilars>.
4
+ This project a prototype implementation of an RO-Crate based collections
5
+ archive and data portal based on the Portland Common Data model of collections
6
+ suitable use in long-term archival repository systems that aim to follow the
7
+ Protocols for Long Term Archival Repository Services
8
+ [PILARS](https://w3id.org/ldac/pilars).
5
9
 
6
- The aim is to provide an API-centred reference implementation of a repository with an access-controlled web portal for data dissemination and deposit:
10
+ The library can be used to mount the API endpoints into your own Fastify or
11
+ Express app.
12
+
13
+ The aim is to provide an API-centred reference implementation of a repository
14
+ with an access-controlled web portal for data dissemination and deposit:
7
15
 
8
16
  - Backend-agnostic RO-Crate storage using pluggable storage-layers
9
- - [OCFL] - the Oxford Common File Layout specification on disk or cloud-based object storage
17
+ - [OCFL] - the Oxford Common File Layout specification on disk or cloud-based
18
+ object storage
10
19
  - Object Storage as used in [PARADISEC]
11
- - A simple RO-Crate file layout (TODO - likely a super-simple protocol for directory hierarchy with the presense on RO-Crate used to indicate that everythig under that directory is a single RO-Crate)
12
- - Authorisation based on the concept of Access (and Deposit, TODO) Licenses using an arms-length process with an external authority such as a REMS instance or other license/group managmenet system
13
- - Based on the princuple that all data MUST have a implementation-neutral natural-language description of its access conditiions stored with it
14
- - Licenses may be based on 'traditional' access control lists maintained in software such as PARADISEC or a license manager such as REMS, (TODO: an example implementation using github groups to manage license access, a simple ACL manager?)).
20
+ - A simple RO-Crate file layout (TODO - likely a super-simple protocol for
21
+ directory hierarchy with the presence on RO-Crate used to indicate that
22
+ everything under that directory is a single RO-Crate)
23
+ - Authorisation based on the concept of Access (and Deposit, TODO) Licenses
24
+ using an arms-length process with an external authority such as a REMS
25
+ instance or other license/group management system
26
+ - Based on the principle that all data MUST have a implementation-neutral
27
+ natural-language description of its access conditions stored with it
28
+ - Licenses may be based on 'traditional' access control lists maintained in
29
+ software such as PARADISEC or a license manager such as REMS, (TODO: an
30
+ example implementation using GitHub groups to manage license access, a
31
+ simple ACL manager?)).
32
+
33
+ ## Prerequisites
34
+
35
+ - Node.js (version 22 or higher)
36
+ - pnpm package manager
37
+ - Database: MySQL or PostgreSQL
38
+ - OpenSearch for search functionality
39
+ - Docker and Docker Compose (for development)
40
+
41
+ ## Quick Start
42
+
43
+ ### 1. Installation
44
+
45
+ ```bash
46
+ # Install the package
47
+ pnpm add arocapi
48
+
49
+ # Install required peer dependencies
50
+ pnpm add @prisma/client @opensearch-project/opensearch
51
+ pnpm add -D prisma
52
+ ```
53
+
54
+ ### 2. Environment Setup
55
+
56
+ Create a `.env` file in your project root:
57
+
58
+ ```env
59
+ # Database Configuration (You can use an DB that Prisma supports)
60
+ DATABASE_URL="mysql://root:password@localhost:3306/catalog"
61
+
62
+ # OpenSearch Configuration
63
+ OPENSEARCH_URL="http://localhost:9200"
64
+ ```
65
+
66
+ ## Creating Your API
67
+
68
+ > [!TIP]
69
+ > We recommend using the Fastify as it will be a native integration
70
+
71
+ ### Option 1: Fastify Implementation
72
+
73
+ Create your Fastify application with Typescript support:
15
74
 
16
- ## Getting started
75
+ ```typescript
76
+ // src/index.ts
77
+ import { Client } from '@opensearch-project/opensearch';
78
+ import arocapi, { AllPublicAccessTransformer } from 'arocapi';
79
+ import Fastify from 'fastify';
80
+ import { PrismaClient } from './generated/prisma/client.js';
17
81
 
18
- This project was bootstrapped with [Fastify-CLI](https://www.npmjs.com/package/fastify-cli)
82
+ // NOTE: Only needed if you are going to use these yourself
83
+ declare module 'fastify' {
84
+ interface FastifyInstance {
85
+ prisma: PrismaClient;
86
+ opensearch: Client;
87
+ }
88
+ }
19
89
 
20
- To run:
90
+ const prisma = new PrismaClient();
91
+
92
+ if (!process.env.OPENSEARCH_URL) {
93
+ throw new Error('OPENSEARCH_URL environment variable is not set');
94
+ }
95
+ const opensearchUrl = process.env.OPENSEARCH_URL;
96
+ const opensearch = new Client({ node: opensearchUrl });
97
+
98
+ const fastify = Fastify({
99
+ logger: true,
100
+ });
101
+
102
+ // For fully public datasets
103
+ fastify.register(arocapi, {
104
+ prisma,
105
+ opensearch,
106
+ accessTransformer: AllPublicAccessTransformer,
107
+ // Required: File handler for serving File entity content
108
+ fileHandler: {
109
+ get: async (file) => {
110
+ const fileUrl = `https://storage.example.com/${file.meta.storagePath}`;
111
+ return { type: 'redirect', url: fileUrl };
112
+ },
113
+ head: async (file) => ({
114
+ contentType: file.mediaType,
115
+ contentLength: file.size,
116
+ }),
117
+ },
118
+ // Required: RO-Crate handler for serving RO-Crate metadata
119
+ roCrateHandler: {
120
+ get: async (entity) => {
121
+ const jsonString = JSON.stringify(entity.rocrate, null, 2);
122
+ return {
123
+ type: 'stream',
124
+ stream: Readable.from([jsonString]),
125
+ metadata: {
126
+ contentType: 'application/ld+json',
127
+ contentLength: Buffer.byteLength(jsonString),
128
+ },
129
+ };
130
+ },
131
+ head: async (entity) => ({
132
+ contentType: 'application/ld+json',
133
+ contentLength: Buffer.byteLength(JSON.stringify(entity.rocrate)),
134
+ }),
135
+ },
136
+ });
137
+
138
+ try {
139
+ await fastify.listen({ port: 3000 });
140
+ } catch (err) {
141
+ fastify.log.error(err);
142
+ process.exit(1);
143
+ }
144
+ ```
145
+
146
+ ### Option 2: Express Implementation
147
+
148
+ Create your Express application:
149
+
150
+ ```typescript
151
+ // src/app.ts
152
+ import { Client } from '@opensearch-project/opensearch';
153
+ import Arocapi from 'arocapi/express';
154
+ import express from 'express';
155
+ import expressListRoutes from 'express-list-routes';
156
+ import { PrismaClient } from './generated/prisma/client.js';
157
+
158
+ const prisma = new PrismaClient();
159
+
160
+ if (!process.env.OPENSEARCH_URL) {
161
+ throw new Error('OPENSEARCH_URL environment variable is not set');
162
+ }
163
+ const opensearchUrl = process.env.OPENSEARCH_URL;
164
+ const opensearch = new Client({ node: opensearchUrl });
165
+
166
+ const app = express();
167
+
168
+ const arocapi = await Arocapi({ opensearch, prisma });
169
+ app.use('/api', arocapi);
170
+
171
+ const port = process.env.PORT || 3000;
172
+ app.listen(port, () => {
173
+ console.log(`API server listening on port ${port}`);
174
+ });
175
+ ```
176
+
177
+ ## Database Setup with Prisma
178
+
179
+ ### 1. Initialize Prisma
21
180
 
22
181
  ```bash
23
- # Bring up the database
24
- docker compose up
182
+ # Initialize prisma with your preferred database provider
183
+ npx prisma init --datasource-provider mysql
184
+ # or for PostgreSQL: npx prisma init --datasource-provider postgresql
185
+ ```
186
+
187
+ ### 2. Configure Prisma Multi-Model Setup
25
188
 
26
- # Generate db client
189
+ Create a `prisma.config.ts` file in your project root:
190
+
191
+ ```typescript
192
+ // prisma.config.ts
193
+ import 'dotenv/config';
194
+ import { defineConfig } from 'prisma/config';
195
+
196
+ export default defineConfig({
197
+ schema: 'prisma',
198
+ });
199
+ ```
200
+
201
+ ### 3. Set Up Model Structure
202
+
203
+ Create the directory structure and link to arocapi models:
204
+
205
+ ```bash
206
+ # Create prisma models directory
207
+ mkdir -p prisma/models
208
+
209
+ # Link to the upstream arocapi models
210
+ cd prisma && ln -s ../node_modules/arocapi/prisma/models upstream && cd ..
211
+ ```
212
+
213
+ ### 4. Configure Prisma Schema
214
+
215
+ Update your `prisma/schema.prisma` file:
216
+
217
+ ```prisma
218
+ // prisma/schema.prisma
219
+ generator client {
220
+ provider = "prisma-client"
221
+ output = "../src/generated/prisma"
222
+ importFileExtension = "js"
223
+ }
224
+
225
+ generator json {
226
+ provider = "prisma-json-types-generator"
227
+ }
228
+
229
+ datasource db {
230
+ provider = "mysql" // or "postgresql"
231
+ url = env("DATABASE_URL")
232
+ }
233
+ ```
234
+
235
+ ### 5. Generate Prisma Client and Run Migrations
236
+
237
+ ```bash
238
+ # Generate the Prisma client
27
239
  npx prisma generate
28
240
 
29
- # Apply db migrations
241
+ # Apply database migrations
30
242
  npx prisma migrate deploy
31
243
 
32
- # Run the app
33
- pnpm run dev
244
+ # Or for development with migration creation
245
+ npx prisma migrate dev
34
246
  ```
35
247
 
36
- ## Available Scripts
248
+ ## Available API Routes
37
249
 
38
- In the project directory, you can run:
250
+ The arocapi provides the following endpoints:
39
251
 
40
- ### `pnpm run dev`
252
+ - `GET /entities` - List all entities with pagination and filtering
253
+ - `GET /entity/:id` - Get a specific entity by ID
254
+ - `GET /entity/:id/rocrate` - Download RO-Crate metadata
255
+ - `GET /files` - List files with pagination and filtering
256
+ - `GET /file/:id` - Download or access file content
257
+ - `POST /search` - Search entities using OpenSearch
41
258
 
42
- To start the app in dev mode.\
43
- Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
259
+ ## Customising Entity Responses
44
260
 
45
- ### `pnpm start`
261
+ The API provides a flexible transformer system for customising entity responses
262
+ through two types of transformers:
46
263
 
47
- For production mode
264
+ ### Access Transformer (Required)
48
265
 
49
- ### `pnpm run test`
266
+ The `accessTransformer` parameter is **required** for security. You must explicitly
267
+ choose how access control is handled for your repository.
50
268
 
51
- Run the test cases.
269
+ **For fully public datasets**, use `AllPublicAccessTransformer`:
52
270
 
53
- ### `pnpm run dbconsole`
271
+ ```typescript
272
+ import arocapi, { AllPublicAccessTransformer } from 'arocapi';
54
273
 
55
- Connect to mysql console
274
+ await server.register(arocapi, {
275
+ prisma,
276
+ opensearch,
277
+ accessTransformer: AllPublicAccessTransformer,
278
+ });
279
+ ```
280
+
281
+ **For restricted content**, implement a custom access transformer:
282
+
283
+ ```typescript
284
+ const accessTransformer = async (entity, { request, fastify }) => {
285
+ // Custom logic to determine access
286
+ const user = await authenticateUser(request);
287
+ const canAccessContent = await checkLicense(entity.contentLicenseId, user);
288
+
289
+ return {
290
+ ...entity,
291
+ access: {
292
+ metadata: true, // Metadata always visible
293
+ content: canAccessContent,
294
+ contentAuthorisationUrl: canAccessContent
295
+ ? undefined
296
+ : 'https://rems.example.com/request-access',
297
+ },
298
+ };
299
+ };
300
+ ```
301
+
302
+ > [!WARNING]
303
+ > The `accessTransformer` is required to prevent accidental exposure of
304
+ > restricted content. You must make an explicit choice about access control for
305
+ > your repository.
306
+
307
+ ### Entity Transformers
308
+
309
+ Optional transformations for enriching or modifying response data. Multiple
310
+ transformers can be chained together.
311
+
312
+ ```typescript
313
+ await server.register(arocapi, {
314
+ prisma,
315
+ opensearch,
316
+ accessTransformer: AllPublicAccessTransformer,
317
+ entityTransformers: [
318
+ // Add computed fields
319
+ (entity) => ({
320
+ ...entity,
321
+ displayName: `${entity.name} [${entity.entityType.split('/').pop()}]`,
322
+ }),
323
+ // Add counts
324
+ async (entity, { fastify }) => {
325
+ const objectCount = entity.memberOf
326
+ ? await fastify.prisma.entity.count({
327
+ where: { memberOf: entity.rocrateId },
328
+ })
329
+ : 0;
330
+
331
+ return {
332
+ ...entity,
333
+ counts: {
334
+ objects: objectCount,
335
+ }
336
+ };
337
+ },
338
+ ],
339
+ });
340
+ ```
341
+
342
+ ### Transformation Pipeline
343
+
344
+ Every entity response flows through this three-stage pipeline:
345
+
346
+ 1. **Base transformer** - Converts database entities to standard format
347
+ 2. **Access transformer** - Adds access control information
348
+ 3. **Entity transformers** - Optional additional transformations
349
+
350
+ ### Common Use Cases
351
+
352
+ **Access control for restricted content:**
353
+
354
+ ```typescript
355
+ accessTransformer: async (entity, { request, fastify }) => {
356
+ const hasAccess = await checkUserPermissions(request, entity.contentLicenseId);
357
+ return {
358
+ ...entity,
359
+ access: {
360
+ metadata: true,
361
+ content: hasAccess,
362
+ },
363
+ };
364
+ }
365
+ ```
366
+
367
+ **Adding computed or derived fields:**
368
+
369
+ ```typescript
370
+ entityTransformers: [
371
+ (entity) => ({
372
+ ...entity,
373
+ shortId: entity.id.split('/').pop(),
374
+ year: extractYear(entity.description),
375
+ }),
376
+ ]
377
+ ```
378
+
379
+ **Fetching related data asynchronously:**
380
+
381
+ ```typescript
382
+ entityTransformers: [
383
+ async (entity, { fastify }) => ({
384
+ ...entity,
385
+ stats: await fetchEntityStats(entity.id, fastify.prisma),
386
+ }),
387
+ ]
388
+ ```
389
+
390
+ ## File Handler System
391
+
392
+ The API provides two separate handler systems for serving different types of content:
393
+
394
+ 1. **File Handler** - Serves file content for Files (`/files/:id`)
395
+ 2. **RO-Crate Handler** - Serves RO-Crate metadata for any entity (`/entity/:id/rocrate`)
396
+
397
+ ### File Handler (Required)
398
+
399
+ The `fileHandler` parameter is **required**. It serves actual file content.
400
+
401
+ ### RO-Crate Handler (Required)
402
+
403
+ The `roCrateHandler` parameter is **required**. It serves RO-Crate metadata as JSON-LD
404
+ for any entity type (Collection, Object, or File).
405
+
406
+ **File Handler Example** (S3 with redirect):
407
+
408
+ ```typescript
409
+ fileHandler: {
410
+ get: async (file) => {
411
+ const command = new GetObjectCommand({
412
+ Bucket: file.meta.bucket,
413
+ Key: file.meta.s3Key,
414
+ });
415
+ const url = await getSignedUrl(s3, command, { expiresIn: 3600 });
416
+
417
+ return { type: 'redirect', url };
418
+ },
419
+ head: async (file) => {
420
+ return {
421
+ contentType: file.mediaType,
422
+ contentLength: file.size,
423
+ };
424
+ },
425
+ }
426
+ ```
427
+
428
+ **File Handler Example** (local filesystem):
429
+
430
+ ```typescript
431
+ fileHandler: {
432
+ get: async (file) => {
433
+ const filePath = `/data/files/${file.meta.storagePath}`;
434
+ const stats = await stat(filePath);
435
+
436
+ return {
437
+ type: 'stream',
438
+ stream: createReadStream(filePath),
439
+ metadata: {
440
+ contentType: file.mediaType,
441
+ contentLength: stats.size,
442
+ lastModified: stats.mtime,
443
+ },
444
+ };
445
+ },
446
+ head: async (file) => {
447
+ const filePath = `/data/files/${file.meta.storagePath}`;
448
+ const stats = await stat(filePath);
449
+
450
+ return {
451
+ contentType: file.mediaType,
452
+ contentLength: stats.size,
453
+ lastModified: stats.mtime,
454
+ };
455
+ },
456
+ }
457
+ ```
458
+
459
+ **RO-Crate Handler Example** (stream from database):
460
+
461
+ ```typescript
462
+ roCrateHandler: {
463
+ get: async (entity) => {
464
+ const jsonString = JSON.stringify(entity.rocrate, null, 2);
465
+
466
+ return {
467
+ type: 'stream',
468
+ stream: Readable.from([jsonString]),
469
+ metadata: {
470
+ contentType: 'application/ld+json',
471
+ contentLength: Buffer.byteLength(jsonString),
472
+ },
473
+ };
474
+ },
475
+ head: async (entity) => {
476
+ const jsonString = JSON.stringify(entity.rocrate);
477
+ return {
478
+ contentType: 'application/ld+json',
479
+ contentLength: Buffer.byteLength(jsonString),
480
+ };
481
+ },
482
+ }
483
+ ```
484
+
485
+ ### File Handler Response Types
486
+
487
+ The file handler must return one of two response types:
488
+
489
+ **Redirect Response** - Redirect to external file location:
490
+
491
+ ```typescript
492
+ { type: 'redirect', url: 'https://storage.example.com/file.wav' }
493
+ ```
494
+
495
+ **Stream Response** - Serve file content directly:
496
+
497
+ ```typescript
498
+ {
499
+ type: 'stream',
500
+ stream: Readable, // Node.js readable stream
501
+ metadata: {
502
+ contentType: 'audio/wav',
503
+ contentLength: 1024,
504
+ etag?: '"abc123"', // Optional
505
+ lastModified?: new Date(), // Optional
506
+ },
507
+ }
508
+ ```
509
+
510
+ ### Query Parameters
511
+
512
+ The `/file/:id` endpoint supports these query parameters:
513
+
514
+ - `disposition` - 'inline' (default) or 'attachment' for download prompts
515
+ - `filename` - Custom filename for Content-Disposition header (defaults to entity.name)
516
+ - `noRedirect` - If true with redirect response, returns JSON `{location: url}` instead of HTTP 302
517
+
518
+ ### HTTP Range Support
519
+
520
+ The endpoint automatically handles HTTP range requests for partial content,
521
+ useful for media streaming:
522
+
523
+ - Returns **206 Partial Content** for valid range requests
524
+ - Returns **416 Range Not Satisfiable** for invalid ranges
525
+ - Sets appropriate `Content-Range` and `Accept-Ranges` headers
526
+
527
+ ### Entity Meta Field
528
+
529
+ The `meta` JSON field in the Entity model stores implementation-specific
530
+ metadata for your file handler:
531
+
532
+ ```typescript
533
+ await prisma.entity.create({
534
+ data: {
535
+ rocrateId: 'http://example.com/file/123',
536
+ name: 'audio.wav',
537
+ entityType: 'http://schema.org/MediaObject',
538
+ // ... other required fields
539
+ meta: {
540
+ bucket: 's3://my-bucket',
541
+ storagePath: 'collections/col-01',
542
+ checksum: 'sha256:abc123...',
543
+ },
544
+ },
545
+ });
546
+ ```
547
+
548
+ Your file handler can use this metadata to locate files in your storage system.
549
+
550
+ ## Development Workflow
551
+
552
+ ### Local Development Setup
553
+
554
+ 1. **Start the services:**
555
+
556
+ ```bash
557
+ # Start MySQL and OpenSearch using docker-compose
558
+ docker compose up -d
559
+ ```
560
+
561
+ 2. **Set up the database:**
562
+
563
+ ```bash
564
+ # Generate Prisma client
565
+ npx prisma generate
566
+
567
+ # Apply database migrations
568
+ npx prisma migrate deploy
569
+ ```
570
+
571
+ 3. **Run your application:**
572
+
573
+ ```bash
574
+ # For development mode
575
+ pnpm run dev
576
+
577
+ # Or start directly
578
+ node dist/app.js
579
+ ```
580
+
581
+ 4. **Access your API:**
582
+ - API: <http://localhost:3000>
583
+ - Database: localhost:3306 (MySQL)
584
+ - OpenSearch: <http://localhost:9200>
585
+
586
+ ### Available Scripts
587
+
588
+ When using arocapi in your project, you can use these scripts:
589
+
590
+ ```bash
591
+ # Development
592
+ pnpm run dev # Start in development mode with hot reload
593
+ pnpm run start # Start in production mode
594
+
595
+ # Database Management
596
+ npx prisma generate # Generate Prisma client
597
+ npx prisma migrate dev # Create and apply new migration
598
+ npx prisma migrate deploy # Apply existing migrations
599
+ npx prisma studio # Open Prisma Studio (database GUI)
600
+
601
+ # Database Console
602
+ docker compose exec db mysql -u root -p catalog # Connect to MySQL console
603
+
604
+ # Testing
605
+ pnpm run test # Run test cases (if configured)
606
+ ```
607
+
608
+ ### Project Structure
609
+
610
+ When implementing arocapi in your project, follow this structure:
611
+
612
+ ```text
613
+ your-project/
614
+ ├── src/
615
+ │ ├── app.ts # Your main application file
616
+ │ └── generated/
617
+ │ └── prisma/ # Generated Prisma client
618
+ ├── prisma/
619
+ │ ├── schema.prisma # Prisma schema
620
+ │ ├── models/ # Your custom models
621
+ │ └── upstream/ # Symlink to arocapi models
622
+ ├── prisma.config.ts # Prisma configuration
623
+ ├── .env # Environment variables
624
+ └── package.json
625
+ ```
56
626
 
57
627
  ## Resources
58
628
 
@@ -60,5 +630,3 @@ Connect to mysql console
60
630
  - [OCFL](https://ocfl.io/)
61
631
  - [PILARS](https://w3id.org/ldac/pilars)
62
632
  - [REMS](https://trust.aaf.edu.au/rems/)
63
-
64
- To learn Fastify, check out the [Fastify documentation](https://fastify.dev/docs/latest/).
package/dist/app.d.ts CHANGED
@@ -1,7 +1,28 @@
1
- import { type AutoloadPluginOptions } from '@fastify/autoload';
1
+ import type { Client } from '@opensearch-project/opensearch';
2
2
  import type { FastifyPluginAsync } from 'fastify';
3
- export type AppOptions = {} & Partial<AutoloadPluginOptions>;
4
- declare const options: AppOptions;
5
- declare const app: FastifyPluginAsync<AppOptions>;
6
- export default app;
7
- export { app, options };
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
+ }
16
+ export type Options = {
17
+ prisma: PrismaClient;
18
+ opensearch: Client;
19
+ disableCors?: boolean;
20
+ accessTransformer: AccessTransformer;
21
+ entityTransformers?: EntityTransformer[];
22
+ fileAccessTransformer: FileAccessTransformer;
23
+ fileTransformers?: FileTransformer[];
24
+ fileHandler: FileHandler;
25
+ roCrateHandler: RoCrateHandler;
26
+ };
27
+ declare const _default: FastifyPluginAsync<Options>;
28
+ export default _default;