-
Notifications
You must be signed in to change notification settings - Fork 122
/
DataAccessor.ts
98 lines (90 loc) · 4.33 KB
/
DataAccessor.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
import type { Readable } from 'node:stream';
import type { Representation } from '../../http/representation/Representation';
import type { RepresentationMetadata } from '../../http/representation/RepresentationMetadata';
import type { ResourceIdentifier } from '../../http/representation/ResourceIdentifier';
import type { Guarded } from '../../util/GuardedStream';
/**
* A DataAccessor is the building block closest to the actual data storage.
* It should not worry about most Solid logic, most of that will be handled before it is called.
* There are a few things it still needs to do, and it is very important every implementation does this:
* * If the input identifier ends with a slash, it should be assumed the identifier is targeting a container.
* * Similarly, if there is no trailing slash it should assume a document.
* * It should always throw a NotFoundHttpError if it does not have data matching the input identifier.
* * DataAccessors should not generate containment triples. This will be done externally using `getChildren`.
*/
export interface DataAccessor {
/**
* Should throw a NotImplementedHttpError if the DataAccessor does not support storing the given Representation.
*
* @param representation - Incoming Representation.
*
* @throws BadRequestHttpError
* If it does not support the incoming data.
*/
canHandle: (representation: Representation) => Promise<void>;
/**
* Returns a data stream stored for the given identifier.
* It can be assumed that the incoming identifier will always correspond to a document.
*
* @param identifier - Identifier for which the data is requested.
*/
getData: (identifier: ResourceIdentifier) => Promise<Guarded<Readable>>;
/**
* Returns the metadata corresponding to the identifier.
* If possible, it is suggested to add a `posix:size` triple to the metadata indicating the binary size.
* This is necessary for range requests.
*
* @param identifier - Identifier for which the metadata is requested.
*/
getMetadata: (identifier: ResourceIdentifier) => Promise<RepresentationMetadata>;
/**
* Returns metadata for all resources in the requested container.
* This should not be all metadata of those resources (but it can be),
* but instead the main metadata you want to show in situations
* where all these resources are presented simultaneously.
* Generally this would be metadata that is present for all of these resources,
* such as resource type or last modified date.
*
* It can be safely assumed that the incoming identifier will always correspond to a container.
*
* @param identifier - Identifier of the parent container.
*/
getChildren: (identifier: ResourceIdentifier) => AsyncIterableIterator<RepresentationMetadata>;
/**
* Writes data and metadata for a document.
* If any data and/or metadata exist for the given identifier, it should be overwritten.
*
* @param identifier - Identifier of the resource.
* @param data - Data to store.
* @param metadata - Metadata to store.
*/
writeDocument: (identifier: ResourceIdentifier, data: Guarded<Readable>, metadata: RepresentationMetadata) =>
Promise<void>;
/**
* Writes metadata for a container.
* If the container does not exist yet it should be created,
* if it does its metadata should be overwritten, except for the containment triples.
*
* @param identifier - Identifier of the container.
* @param metadata - Metadata to store.
*/
writeContainer: (identifier: ResourceIdentifier, metadata: RepresentationMetadata) => Promise<void>;
/**
* Writes metadata for a resource.
* It can safely be assumed that the subject resource already exists.
*
* @param identifier - Identifier of the subject resource.
* @param metadata - Metadata to store.
*/
writeMetadata: (identifier: ResourceIdentifier, metadata: RepresentationMetadata) => Promise<void>;
/**
* Deletes the resource and its corresponding metadata.
*
* Solid, §5.4: "When a contained resource is deleted, the server MUST also remove the corresponding containment
* triple, which has the effect of removing the deleted resource from the containing container."
* https://solid.github.io/specification/protocol#deleting-resources
*
* @param identifier - Resource to delete.
*/
deleteResource: (identifier: ResourceIdentifier) => Promise<void>;
}