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.
- package/README.md +597 -29
- package/dist/app.d.ts +27 -6
- package/dist/app.js +76 -17
- package/dist/app.js.map +1 -1
- package/dist/app.test.js +124 -0
- package/dist/app.test.js.map +1 -0
- package/dist/express.d.ts +3 -2
- package/dist/express.js +11 -11
- package/dist/express.js.map +1 -1
- package/dist/index.dev.d.ts +8 -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 +99 -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 +8 -0
- package/dist/routes/entities.js +75 -0
- package/dist/routes/entities.js.map +1 -0
- 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 +8 -0
- package/dist/routes/entity.js +45 -0
- package/dist/routes/entity.js.map +1 -0
- 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 +111 -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 +61 -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 +8 -0
- package/dist/routes/{search/index.js → search.js} +45 -19
- package/dist/routes/search.js.map +1 -0
- 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 +34 -25
- 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/schema.prisma +1 -20
- package/prisma.config.ts +6 -7
- package/src/__snapshots__/app.test.ts.snap +8 -0
- package/src/app.test.ts +158 -0
- package/src/app.ts +150 -30
- package/src/express.ts +12 -11
- 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 +66 -0
- package/src/routes/__snapshots__/search.test.ts.snap +139 -0
- package/src/routes/crate.test.ts +441 -0
- package/src/routes/crate.ts +141 -0
- package/src/routes/entities.test.ts +284 -0
- package/src/routes/entities.ts +101 -0
- package/src/routes/entity.test.ts +132 -0
- package/src/routes/entity.ts +63 -0
- package/src/routes/file.test.ts +399 -0
- package/src/routes/file.ts +153 -0
- package/src/routes/files.test.ts +303 -0
- package/src/routes/files.ts +87 -0
- package/src/routes/search.test.ts +807 -0
- package/src/routes/{search/index.ts → search.ts} +67 -24
- 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/plugins/cors.d.ts +0 -3
- package/dist/plugins/cors.js +0 -6
- package/dist/plugins/cors.js.map +0 -1
- package/dist/plugins/opensearch.d.ts +0 -9
- package/dist/plugins/opensearch.js +0 -22
- package/dist/plugins/opensearch.js.map +0 -1
- package/dist/plugins/prisma.d.ts +0 -8
- package/dist/plugins/prisma.js +0 -11
- package/dist/plugins/prisma.js.map +0 -1
- package/dist/plugins/sensible.d.ts +0 -3
- package/dist/plugins/sensible.js +0 -6
- package/dist/plugins/sensible.js.map +0 -1
- package/dist/plugins/support.d.ts +0 -9
- package/dist/plugins/support.js +0 -5
- package/dist/plugins/support.js.map +0 -1
- package/dist/plugins/validation.d.ts +0 -3
- package/dist/plugins/validation.js +0 -32
- package/dist/plugins/validation.js.map +0 -1
- package/dist/routes/entities/index.d.ts +0 -3
- package/dist/routes/entities/index.js +0 -63
- package/dist/routes/entities/index.js.map +0 -1
- package/dist/routes/entity/index.d.ts +0 -3
- package/dist/routes/entity/index.js +0 -24
- package/dist/routes/entity/index.js.map +0 -1
- package/dist/routes/search/index.d.ts +0 -3
- package/dist/routes/search/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/plugins/README.md +0 -16
- package/src/plugins/cors.ts +0 -11
- package/src/plugins/opensearch.ts +0 -32
- package/src/plugins/prisma.ts +0 -23
- package/src/plugins/sensible.ts +0 -11
- package/src/plugins/support.ts +0 -20
- package/src/plugins/validation.ts +0 -48
- package/src/routes/README.md +0 -29
- package/src/routes/entities/index.ts +0 -83
- package/src/routes/entity/index.ts +0 -28
- 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/README.md
CHANGED
|
@@ -1,58 +1,628 @@
|
|
|
1
1
|
|
|
2
2
|
# An RO-Crate API for Data Collections : Arocapi
|
|
3
3
|
|
|
4
|
-
This project
|
|
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
|
|
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
|
|
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
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
24
|
-
|
|
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
|
-
|
|
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
|
|
241
|
+
# Apply database migrations
|
|
30
242
|
npx prisma migrate deploy
|
|
31
243
|
|
|
32
|
-
#
|
|
33
|
-
|
|
244
|
+
# Or for development with migration creation
|
|
245
|
+
npx prisma migrate dev
|
|
34
246
|
```
|
|
35
247
|
|
|
36
|
-
## Available
|
|
248
|
+
## Available API Routes
|
|
37
249
|
|
|
38
|
-
|
|
250
|
+
The arocapi provides the following endpoints:
|
|
39
251
|
|
|
40
|
-
|
|
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
|
-
|
|
43
|
-
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
|
|
259
|
+
## Customising Entity Responses
|
|
44
260
|
|
|
45
|
-
|
|
261
|
+
The API provides a flexible transformer system for customising entity responses
|
|
262
|
+
through two types of transformers:
|
|
46
263
|
|
|
47
|
-
|
|
264
|
+
### Access Transformer (Required)
|
|
48
265
|
|
|
49
|
-
|
|
266
|
+
The `accessTransformer` parameter is **required** for security. You must explicitly
|
|
267
|
+
choose how access control is handled for your repository.
|
|
50
268
|
|
|
51
|
-
|
|
269
|
+
**For fully public datasets**, use `AllPublicAccessTransformer`:
|
|
52
270
|
|
|
53
|
-
|
|
271
|
+
```typescript
|
|
272
|
+
import arocapi, { AllPublicAccessTransformer } from 'arocapi';
|
|
54
273
|
|
|
55
|
-
|
|
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 {
|
|
1
|
+
import type { Client } from '@opensearch-project/opensearch';
|
|
2
2
|
import type { FastifyPluginAsync } from 'fastify';
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
export default
|
|
7
|
-
export {
|
|
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;
|