euclid-ndk 0.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/LICENSE +201 -0
- package/README.md +603 -0
- package/dist/auth/index.d.ts +18 -0
- package/dist/auth/index.d.ts.map +1 -0
- package/dist/auth/index.js +17 -0
- package/dist/auth/index.js.map +1 -0
- package/dist/auth/rfc9421.d.ts +112 -0
- package/dist/auth/rfc9421.d.ts.map +1 -0
- package/dist/auth/rfc9421.js +452 -0
- package/dist/auth/rfc9421.js.map +1 -0
- package/dist/auth/scheme.d.ts +46 -0
- package/dist/auth/scheme.d.ts.map +1 -0
- package/dist/auth/scheme.js +44 -0
- package/dist/auth/scheme.js.map +1 -0
- package/dist/auth/signable.d.ts +37 -0
- package/dist/auth/signable.d.ts.map +1 -0
- package/dist/auth/signable.js +70 -0
- package/dist/auth/signable.js.map +1 -0
- package/dist/auth/sigv4.d.ts +72 -0
- package/dist/auth/sigv4.d.ts.map +1 -0
- package/dist/auth/sigv4.js +227 -0
- package/dist/auth/sigv4.js.map +1 -0
- package/dist/credentials.d.ts +56 -0
- package/dist/credentials.d.ts.map +1 -0
- package/dist/credentials.js +135 -0
- package/dist/credentials.js.map +1 -0
- package/dist/dto/com.d.ts +101 -0
- package/dist/dto/com.d.ts.map +1 -0
- package/dist/dto/com.js +132 -0
- package/dist/dto/com.js.map +1 -0
- package/dist/dto/eag.d.ts +104 -0
- package/dist/dto/eag.d.ts.map +1 -0
- package/dist/dto/eag.js +70 -0
- package/dist/dto/eag.js.map +1 -0
- package/dist/dto/eam.d.ts +105 -0
- package/dist/dto/eam.d.ts.map +1 -0
- package/dist/dto/eam.js +98 -0
- package/dist/dto/eam.js.map +1 -0
- package/dist/dto/eap.d.ts +88 -0
- package/dist/dto/eap.d.ts.map +1 -0
- package/dist/dto/eap.js +54 -0
- package/dist/dto/eap.js.map +1 -0
- package/dist/dto/ekm.d.ts +109 -0
- package/dist/dto/ekm.d.ts.map +1 -0
- package/dist/dto/ekm.js +78 -0
- package/dist/dto/ekm.js.map +1 -0
- package/dist/dto/ekv.d.ts +73 -0
- package/dist/dto/ekv.d.ts.map +1 -0
- package/dist/dto/ekv.js +45 -0
- package/dist/dto/ekv.js.map +1 -0
- package/dist/dto/ens.d.ts +84 -0
- package/dist/dto/ens.d.ts.map +1 -0
- package/dist/dto/ens.js +72 -0
- package/dist/dto/ens.js.map +1 -0
- package/dist/dto/eqs.d.ts +160 -0
- package/dist/dto/eqs.d.ts.map +1 -0
- package/dist/dto/eqs.js +120 -0
- package/dist/dto/eqs.js.map +1 -0
- package/dist/dto/esm.d.ts +192 -0
- package/dist/dto/esm.d.ts.map +1 -0
- package/dist/dto/esm.js +147 -0
- package/dist/dto/esm.js.map +1 -0
- package/dist/dto/ess.d.ts +49 -0
- package/dist/dto/ess.d.ts.map +1 -0
- package/dist/dto/ess.js +30 -0
- package/dist/dto/ess.js.map +1 -0
- package/dist/dto/json.d.ts +24 -0
- package/dist/dto/json.d.ts.map +1 -0
- package/dist/dto/json.js +47 -0
- package/dist/dto/json.js.map +1 -0
- package/dist/errors.d.ts +40 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +73 -0
- package/dist/errors.js.map +1 -0
- package/dist/http/client.d.ts +96 -0
- package/dist/http/client.d.ts.map +1 -0
- package/dist/http/client.js +258 -0
- package/dist/http/client.js.map +1 -0
- package/dist/index.d.ts +93 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +110 -0
- package/dist/index.js.map +1 -0
- package/dist/modules/base.d.ts +121 -0
- package/dist/modules/base.d.ts.map +1 -0
- package/dist/modules/base.js +142 -0
- package/dist/modules/base.js.map +1 -0
- package/dist/modules/eag.d.ts +166 -0
- package/dist/modules/eag.d.ts.map +1 -0
- package/dist/modules/eag.js +189 -0
- package/dist/modules/eag.js.map +1 -0
- package/dist/modules/eam.d.ts +314 -0
- package/dist/modules/eam.d.ts.map +1 -0
- package/dist/modules/eam.js +641 -0
- package/dist/modules/eam.js.map +1 -0
- package/dist/modules/eap.d.ts +204 -0
- package/dist/modules/eap.d.ts.map +1 -0
- package/dist/modules/eap.js +218 -0
- package/dist/modules/eap.js.map +1 -0
- package/dist/modules/ekm.d.ts +182 -0
- package/dist/modules/ekm.d.ts.map +1 -0
- package/dist/modules/ekm.js +228 -0
- package/dist/modules/ekm.js.map +1 -0
- package/dist/modules/ekv.d.ts +189 -0
- package/dist/modules/ekv.d.ts.map +1 -0
- package/dist/modules/ekv.js +212 -0
- package/dist/modules/ekv.js.map +1 -0
- package/dist/modules/ens.d.ts +122 -0
- package/dist/modules/ens.d.ts.map +1 -0
- package/dist/modules/ens.js +167 -0
- package/dist/modules/ens.js.map +1 -0
- package/dist/modules/eqs.d.ts +283 -0
- package/dist/modules/eqs.d.ts.map +1 -0
- package/dist/modules/eqs.js +355 -0
- package/dist/modules/eqs.js.map +1 -0
- package/dist/modules/esm.d.ts +358 -0
- package/dist/modules/esm.d.ts.map +1 -0
- package/dist/modules/esm.js +660 -0
- package/dist/modules/esm.js.map +1 -0
- package/dist/modules/ess.d.ts +96 -0
- package/dist/modules/ess.d.ts.map +1 -0
- package/dist/modules/ess.js +110 -0
- package/dist/modules/ess.js.map +1 -0
- package/dist/url.d.ts +31 -0
- package/dist/url.d.ts.map +1 -0
- package/dist/url.js +47 -0
- package/dist/url.js.map +1 -0
- package/package.json +47 -0
|
@@ -0,0 +1,358 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ESM - euclid's storage module: buckets, objects, attributes, subscriptions and transfers.
|
|
3
|
+
*
|
|
4
|
+
* One object, {@link EuclidEsm}, built from a session that has already logged in:
|
|
5
|
+
*
|
|
6
|
+
* ```ts
|
|
7
|
+
* const esm = (await Euclid.forServer(url).login("jens", "secret")).esm();
|
|
8
|
+
* const bucket = await esm.createBucket("reports");
|
|
9
|
+
* await esm.uploadFile(bucket.ern, "2026/q3.pdf", "q3.pdf");
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* Most of what it does is the same JSON action every other module speaks. Four actions are not:
|
|
13
|
+
* `put-object`, `get-object`, `upload-part` and `download-part` carry the object's bytes themselves,
|
|
14
|
+
* with the bucket, the key and the part number riding as headers instead of in a body - which is what
|
|
15
|
+
* keeps a 5 MiB part 5 MiB on the wire rather than a third larger as base64 inside JSON.
|
|
16
|
+
*
|
|
17
|
+
* Those four also authenticate differently: they present the session's bearer token rather than a
|
|
18
|
+
* signature, which is what euclid-cli, euclid-jdk and euclid-pdk do for the same four actions, so
|
|
19
|
+
* every client writes objects the same way. A session that asked for `AUTH_SIGNATURE` signs
|
|
20
|
+
* them anyway - it asked not to be handed a token silently, and a signature over raw bytes is exact
|
|
21
|
+
* here in a way it is not in every language.
|
|
22
|
+
*/
|
|
23
|
+
import { type SubscribeResult, type Subscription, type Variant, type VariantInput } from "../dto/com.js";
|
|
24
|
+
import { type BucketEvent, type CreateBucketResult, type DeleteObjectsResult, type DisableEncryptionResult, type EnableEncryptionResult, type EsmObject, type ObjectAttribute, type PurgeBucketResult, type RenameBucketResult, type SetBucketInternalResult, type StoredObject, type TouchObjectResult, type Bucket } from "../dto/esm.js";
|
|
25
|
+
import { type Page } from "../dto/eam.js";
|
|
26
|
+
import type { Response } from "../http/client.js";
|
|
27
|
+
import { ModuleClient, type Bytes, type ListOptions } from "./base.js";
|
|
28
|
+
import type { EuclidSession } from "./eam.js";
|
|
29
|
+
export declare const TARGET = "esm";
|
|
30
|
+
/** The object events a subscription can ask for. Asking for none asks for all of them. */
|
|
31
|
+
export declare const OBJECT_CREATED = "esm.object.created";
|
|
32
|
+
export declare const OBJECT_UPDATED = "esm.object.updated";
|
|
33
|
+
export declare const OBJECT_DELETED = "esm.object.deleted";
|
|
34
|
+
/**
|
|
35
|
+
* How much of a file goes into one part. Larger parts mean fewer round trips and more memory in
|
|
36
|
+
* flight; 5 MiB is what euclid-cli, euclid-jdk and euclid-pdk use, which is what makes a file
|
|
37
|
+
* uploaded by one of them arrive in the same pieces as one uploaded by another.
|
|
38
|
+
*/
|
|
39
|
+
export declare const DEFAULT_PART_SIZE: number;
|
|
40
|
+
/** How many parts travel at once. */
|
|
41
|
+
export declare const DEFAULT_CONCURRENCY = 4;
|
|
42
|
+
/**
|
|
43
|
+
* How many attempts one step of a transfer gets. Transfers are long and made of many steps, so a
|
|
44
|
+
* transient failure in any of them would otherwise throw away everything already transferred.
|
|
45
|
+
*/
|
|
46
|
+
export declare const MAX_PART_ATTEMPTS = 4;
|
|
47
|
+
/** The delay before retrying, in milliseconds, multiplied by the attempt number. */
|
|
48
|
+
export declare const PART_RETRY_BASE_DELAY_MS = 500;
|
|
49
|
+
/**
|
|
50
|
+
* What `get-object` answers when the object is at or above the size the caller said it would accept.
|
|
51
|
+
* Not an error in {@link EuclidEsm.downloadFile}: it is the server saying the object needs the
|
|
52
|
+
* multipart path.
|
|
53
|
+
*/
|
|
54
|
+
export declare const PAYLOAD_TOO_LARGE = 413;
|
|
55
|
+
/** The actions that carry raw bytes rather than JSON - see this module's documentation. */
|
|
56
|
+
export declare const BYTE_ACTIONS: string[];
|
|
57
|
+
/** How a bucket listing is paged, and whether euclid's own buckets are in it. */
|
|
58
|
+
export interface ListBucketsOptions extends ListOptions {
|
|
59
|
+
includeInternal?: boolean;
|
|
60
|
+
}
|
|
61
|
+
/** How an object listing is paged, and whether the directory markers are in it. */
|
|
62
|
+
export interface ListObjectsOptions extends ListOptions {
|
|
63
|
+
includeDirectories?: boolean;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* The two attribute maps a write carries, and they are not the same one.
|
|
67
|
+
*
|
|
68
|
+
* `attributes` are the caller's own, listed back by {@link EuclidEsm.listObjectAttributes} and
|
|
69
|
+
* meaningless to euclid. `systemAttributes` are euclid's envelope: they travel with the object across
|
|
70
|
+
* every hop and are never mixed into the caller's. The one euclid acts on is `priority` - an object
|
|
71
|
+
* written with `systemAttributes: { priority: PRIORITY_LOW }` produces a notification carrying it,
|
|
72
|
+
* which is how a producer's decision survives a hop through a bucket.
|
|
73
|
+
*/
|
|
74
|
+
export interface AttributeOptions {
|
|
75
|
+
attributes?: Record<string, VariantInput>;
|
|
76
|
+
systemAttributes?: Record<string, VariantInput>;
|
|
77
|
+
}
|
|
78
|
+
/** How a file is cut up on the way out, and what the object it becomes carries. */
|
|
79
|
+
export interface UploadOptions extends AttributeOptions {
|
|
80
|
+
partSize?: number;
|
|
81
|
+
concurrency?: number;
|
|
82
|
+
}
|
|
83
|
+
/** How an object is fetched: in what parts, and how many at a time. */
|
|
84
|
+
export interface DownloadOptions {
|
|
85
|
+
partSize?: number;
|
|
86
|
+
concurrency?: number;
|
|
87
|
+
}
|
|
88
|
+
/** Which of a bucket's events a subscription asks for, and which keys they have to match. */
|
|
89
|
+
export interface SubscribeOptions {
|
|
90
|
+
/** {@link OBJECT_CREATED}, {@link OBJECT_UPDATED}, {@link OBJECT_DELETED}, or none for all. */
|
|
91
|
+
eventTypes?: Iterable<string>;
|
|
92
|
+
prefix?: string;
|
|
93
|
+
/** Whether the zero-byte directory markers are delivered too. */
|
|
94
|
+
directories?: boolean;
|
|
95
|
+
}
|
|
96
|
+
/** Which of a bucket's objects are re-announced, and whether the caller waits for it. */
|
|
97
|
+
export interface TouchObjectOptions {
|
|
98
|
+
prefix?: string;
|
|
99
|
+
background?: boolean;
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* The notification a bucket subscription delivered, out of the message that carried it.
|
|
103
|
+
*
|
|
104
|
+
* A subscription puts its notification into a queue or a topic as an ordinary message, so nothing
|
|
105
|
+
* about receiving it is special - whatever reads that queue hands the message body to this.
|
|
106
|
+
*
|
|
107
|
+
* @throws {SyntaxError} if the body is not JSON at all.
|
|
108
|
+
*/
|
|
109
|
+
export declare function parseBucketEvent(messageBody: string | Buffer): BucketEvent;
|
|
110
|
+
/**
|
|
111
|
+
* ESM's operations, on the credentials of the session that created it.
|
|
112
|
+
*
|
|
113
|
+
* Built by {@link EuclidSession.esm} rather than directly, so that it shares that session's identity,
|
|
114
|
+
* namespace and connection settings - and follows them as they change.
|
|
115
|
+
*/
|
|
116
|
+
export declare class EuclidEsm extends ModuleClient {
|
|
117
|
+
#private;
|
|
118
|
+
/**
|
|
119
|
+
* How long the byte-carrying actions may take, in milliseconds, or null for the session's own
|
|
120
|
+
* timeout. Worth raising: the session's default is sized for an action that answers from a
|
|
121
|
+
* database, and a 5 MiB part on a slow link is not that.
|
|
122
|
+
*/
|
|
123
|
+
transferTimeoutMs: number | null;
|
|
124
|
+
/**
|
|
125
|
+
* The delay before one step of a transfer is tried again, multiplied by the attempt number.
|
|
126
|
+
*
|
|
127
|
+
* A field rather than a constant because it is the one thing about a retry a caller may reasonably
|
|
128
|
+
* want to change: nothing in a test suite wants to wait out a backoff that exists to be kind to a
|
|
129
|
+
* struggling server.
|
|
130
|
+
*/
|
|
131
|
+
retryBaseDelayMs: number;
|
|
132
|
+
constructor(session: EuclidSession);
|
|
133
|
+
/**
|
|
134
|
+
* {@link parseBucketEvent}, reachable from the client so that the call that reads a subscription's
|
|
135
|
+
* messages is found next to the call that created the subscription.
|
|
136
|
+
*/
|
|
137
|
+
static readonly parseBucketEvent: typeof parseBucketEvent;
|
|
138
|
+
/**
|
|
139
|
+
* Creates a bucket, and answers with the ERN everything else names it by.
|
|
140
|
+
*
|
|
141
|
+
* `internal` marks it as euclid's own plumbing rather than somebody's bucket, which leaves it out of
|
|
142
|
+
* an ordinary listing - see {@link setBucketInternal}, which is how a bucket that already exists
|
|
143
|
+
* changes its mind about that.
|
|
144
|
+
*/
|
|
145
|
+
createBucket(name: string, internal?: boolean): Promise<CreateBucketResult>;
|
|
146
|
+
/** Deletes a bucket. It has to be empty; {@link purgeBucket} is what makes it so. */
|
|
147
|
+
deleteBucket(ern: string): Promise<void>;
|
|
148
|
+
/**
|
|
149
|
+
* One page of buckets, and how many exist in total.
|
|
150
|
+
*
|
|
151
|
+
* euclid's own buckets are left out unless `includeInternal` asks for them, so a listing shows what
|
|
152
|
+
* a person would recognise rather than the artifact bucket applications are deployed from.
|
|
153
|
+
*/
|
|
154
|
+
listBuckets(options?: ListBucketsOptions): Promise<Page<Bucket>>;
|
|
155
|
+
/** The ERN of the bucket of this name, in the session's account and namespace. */
|
|
156
|
+
getBucketErn(name: string): Promise<string>;
|
|
157
|
+
/** How many bytes a bucket holds. */
|
|
158
|
+
getBucketSize(ern: string): Promise<number>;
|
|
159
|
+
/**
|
|
160
|
+
* Renames a bucket, and with it every object and subscription that named the old one.
|
|
161
|
+
*
|
|
162
|
+
* The ERN changes too, and nothing answers to the old one afterwards, so the one in the result is
|
|
163
|
+
* what later calls have to use. Refused rather than merged when a bucket of the new name exists.
|
|
164
|
+
*/
|
|
165
|
+
renameBucket(ern: string, newName: string): Promise<RenameBucketResult>;
|
|
166
|
+
/**
|
|
167
|
+
* Marks a bucket as euclid's own plumbing, or stops doing so.
|
|
168
|
+
*
|
|
169
|
+
* Separate from creating one because the bucket this exists for usually predates anybody thinking
|
|
170
|
+
* about it, and reversible for the same reason: a flag that can only be set is one nobody dares set.
|
|
171
|
+
*/
|
|
172
|
+
setBucketInternal(ern: string, internal?: boolean): Promise<SetBucketInternalResult>;
|
|
173
|
+
/**
|
|
174
|
+
* Deletes a bucket's objects, leaving the bucket itself in place.
|
|
175
|
+
*
|
|
176
|
+
* A prefix narrows it to the keys that start with that; an empty one purges everything.
|
|
177
|
+
*/
|
|
178
|
+
purgeBucket(ern: string, prefix?: string): Promise<PurgeBucketResult>;
|
|
179
|
+
/**
|
|
180
|
+
* Encrypts every object written to this bucket from now on, under an EKM key.
|
|
181
|
+
*
|
|
182
|
+
* What it does not do is touch the objects already there: their bytes stay as they were stored, each
|
|
183
|
+
* one records the key it is under, and the result says how many such objects there are.
|
|
184
|
+
* Re-encrypting them is a decision for whoever owns the data.
|
|
185
|
+
*
|
|
186
|
+
* A named key has to exist and be usable for encryption. An unnamed one is created here as AES-256
|
|
187
|
+
* and belongs to EKM from that moment on - which means deleting it there is what makes this
|
|
188
|
+
* bucket's objects unrecoverable.
|
|
189
|
+
*/
|
|
190
|
+
enableEncryption(bucketErn: string, keyId?: string): Promise<EnableEncryptionResult>;
|
|
191
|
+
/**
|
|
192
|
+
* Stops encrypting new objects written to a bucket.
|
|
193
|
+
*
|
|
194
|
+
* The mirror image of {@link enableEncryption} in one respect and no other: it says what happens to
|
|
195
|
+
* the next upload, and it is not an undo. Nothing already stored is decrypted or rewritten, and the
|
|
196
|
+
* key is left alone rather than revoked - those objects are still under it.
|
|
197
|
+
*/
|
|
198
|
+
disableEncryption(bucketErn: string): Promise<DisableEncryptionResult>;
|
|
199
|
+
/** Tags a bucket. A key that is already tagged keeps its value - {@link setBucketTag} overwrites. */
|
|
200
|
+
addBucketTag(bucketErn: string, key: string, value: string): Promise<void>;
|
|
201
|
+
/** Tags a bucket, overwriting any value the key already had. */
|
|
202
|
+
setBucketTag(bucketErn: string, key: string, value: string): Promise<void>;
|
|
203
|
+
/** Removes a tag from a bucket. */
|
|
204
|
+
deleteBucketTag(bucketErn: string, key: string): Promise<void>;
|
|
205
|
+
/**
|
|
206
|
+
* One page of a bucket's objects, and how many it holds in total.
|
|
207
|
+
*
|
|
208
|
+
* Keys are opaque strings, so a bucket only has "directories" in the sense that keys share a prefix;
|
|
209
|
+
* the markers for them are left out unless `includeDirectories` asks for them.
|
|
210
|
+
*/
|
|
211
|
+
listObjects(bucketErn: string, options?: ListObjectsOptions): Promise<Page<EsmObject>>;
|
|
212
|
+
/**
|
|
213
|
+
* How many objects a bucket holds. Cheaper than listing them when only the number matters - the
|
|
214
|
+
* server counts rather than paging every object back to the caller.
|
|
215
|
+
*/
|
|
216
|
+
getObjectCount(bucketErn: string, prefix?: string): Promise<number>;
|
|
217
|
+
/** Deletes one object, by its own ERN. */
|
|
218
|
+
deleteObject(ern: string): Promise<void>;
|
|
219
|
+
/**
|
|
220
|
+
* Deletes several named objects from a bucket in one call.
|
|
221
|
+
*
|
|
222
|
+
* A key that names no object is not an error, so the result reports both how many keys were asked
|
|
223
|
+
* for and how many objects went. Deleting everything under a prefix is {@link purgeBucket} rather
|
|
224
|
+
* than a variant of this - the server refuses keys and a prefix in the same request, since answering
|
|
225
|
+
* both would delete more than either.
|
|
226
|
+
*
|
|
227
|
+
* `background` has the server answer as soon as it has taken the work on rather than when it has
|
|
228
|
+
* finished, in which case the count is what it took on.
|
|
229
|
+
*/
|
|
230
|
+
deleteObjects(bucketErn: string, keys: readonly string[], background?: boolean): Promise<DeleteObjectsResult>;
|
|
231
|
+
/**
|
|
232
|
+
* Copies an object, leaving the source in place.
|
|
233
|
+
*
|
|
234
|
+
* The copy gets its own bytes on disk and its own ERN, so the two are independent from here on. Both
|
|
235
|
+
* ends are permission-checked, and an existing object at the target is refused with HTTP 409 rather
|
|
236
|
+
* than silently replaced.
|
|
237
|
+
*/
|
|
238
|
+
copyObject(sourceBucketErn: string, sourceKey: string, targetBucketErn: string, targetKey: string): Promise<EsmObject>;
|
|
239
|
+
/**
|
|
240
|
+
* Moves an object to another bucket or key, removing the source.
|
|
241
|
+
*
|
|
242
|
+
* The bytes are not copied - the same file answers to a different key from now on - so this costs
|
|
243
|
+
* the same whatever the object's size. Refuses an existing target exactly as {@link copyObject} does.
|
|
244
|
+
*/
|
|
245
|
+
moveObject(sourceBucketErn: string, sourceKey: string, targetBucketErn: string, targetKey: string): Promise<EsmObject>;
|
|
246
|
+
/**
|
|
247
|
+
* Renames an object within its bucket - a {@link moveObject} that cannot leave it, which is the
|
|
248
|
+
* whole difference between the two.
|
|
249
|
+
*/
|
|
250
|
+
renameObject(bucketErn: string, key: string, newKey: string): Promise<EsmObject>;
|
|
251
|
+
/**
|
|
252
|
+
* Re-announces objects already in a bucket, so a listener that missed their creation events hears
|
|
253
|
+
* about them now.
|
|
254
|
+
*
|
|
255
|
+
* Nothing about the objects changes - not a byte, not their modified time. "Touch" here means what
|
|
256
|
+
* it does to listeners, not what it does to storage: a timestamp is something consumers compare
|
|
257
|
+
* against, and moving it would make this destructive in exactly the way it is trying not to be.
|
|
258
|
+
*
|
|
259
|
+
* `background` is what a bucket of any size wants: the announcement is per object, and holding a
|
|
260
|
+
* request open for all of them is a request that times out.
|
|
261
|
+
*/
|
|
262
|
+
touchObject(bucketErn: string, options?: TouchObjectOptions): Promise<TouchObjectResult>;
|
|
263
|
+
/**
|
|
264
|
+
* Adds a user-defined attribute to an object. One of that name already there keeps its value -
|
|
265
|
+
* {@link setObjectAttribute} overwrites.
|
|
266
|
+
*
|
|
267
|
+
* The value is a {@link Variant}, or a plain value to be tagged as one - see
|
|
268
|
+
* {@link import("../dto/com.js").variantOf}.
|
|
269
|
+
*/
|
|
270
|
+
addObjectAttribute(ern: string, name: string, value: VariantInput): Promise<ObjectAttribute>;
|
|
271
|
+
/** Sets a user-defined attribute on an object, overwriting any value it already had. */
|
|
272
|
+
setObjectAttribute(ern: string, name: string, value: VariantInput): Promise<ObjectAttribute>;
|
|
273
|
+
/** Every user-defined attribute of an object, keyed by name. */
|
|
274
|
+
listObjectAttributes(ern: string): Promise<Record<string, Variant>>;
|
|
275
|
+
/** Deletes one user-defined attribute from an object. */
|
|
276
|
+
deleteObjectAttribute(ern: string, name: string): Promise<void>;
|
|
277
|
+
/**
|
|
278
|
+
* Announces a bucket's object events to a queue or a topic from now on.
|
|
279
|
+
*
|
|
280
|
+
* What lands there is a {@link BucketEvent}, carried as the body of an ordinary message - see
|
|
281
|
+
* {@link parseBucketEvent}. The filters are applied by the server as it publishes, so a subscription
|
|
282
|
+
* only ever delivers what it asked for rather than the target receiving everything and discarding
|
|
283
|
+
* most of it.
|
|
284
|
+
*
|
|
285
|
+
* Not idempotent: a second call registers a second subscription and the target then receives every
|
|
286
|
+
* matching event twice, so a caller that may run twice checks {@link listSubscriptions} first.
|
|
287
|
+
*
|
|
288
|
+
* @param bucketErn bucket resource name
|
|
289
|
+
* @param targetType {@link QUEUE} or {@link TOPIC}, which is also what decides how a bare target
|
|
290
|
+
* name is resolved.
|
|
291
|
+
* @param targetErn target resource name
|
|
292
|
+
* @param options call options
|
|
293
|
+
*/
|
|
294
|
+
subscribe(bucketErn: string, targetType: string, targetErn: string, options?: SubscribeOptions): Promise<SubscribeResult>;
|
|
295
|
+
/**
|
|
296
|
+
* Removes a subscription, by the ERN {@link subscribe} answered with - not the bucket's, and not the
|
|
297
|
+
* target's.
|
|
298
|
+
*/
|
|
299
|
+
unsubscribe(ern: string): Promise<void>;
|
|
300
|
+
/** Every subscription currently registered on a bucket. */
|
|
301
|
+
listSubscriptions(bucketErn: string): Promise<Subscription[]>;
|
|
302
|
+
/**
|
|
303
|
+
* Uploads an object in a single request, skipping the multipart sequence entirely.
|
|
304
|
+
*
|
|
305
|
+
* A string is stored as its UTF-8 bytes, which is what the object then is; anything that matters
|
|
306
|
+
* about the encoding is the caller's to decide before calling this.
|
|
307
|
+
*
|
|
308
|
+
* Takes two attribute maps, which are not the same one - see {@link AttributeOptions}.
|
|
309
|
+
*/
|
|
310
|
+
putObject(bucketErn: string, key: string, data: Bytes, options?: AttributeOptions): Promise<StoredObject>;
|
|
311
|
+
/**
|
|
312
|
+
* Downloads an object's bytes in a single request.
|
|
313
|
+
*
|
|
314
|
+
* The size limit is the server's to enforce rather than this client's: a download's size is not
|
|
315
|
+
* known until the server is asked, unlike an upload's, so the caller declares how large a response
|
|
316
|
+
* it is willing to take and an object at or above that comes back as HTTP 413.
|
|
317
|
+
* {@link downloadFile} uses exactly that to decide whether an object needs the multipart path.
|
|
318
|
+
*/
|
|
319
|
+
getObject(bucketErn: string, key: string, maxInlineSize?: number): Promise<Buffer>;
|
|
320
|
+
/**
|
|
321
|
+
* Uploads a local file in parts, several at a time.
|
|
322
|
+
*
|
|
323
|
+
* The file is read a part at a time rather than into memory, and no more than `concurrency` parts
|
|
324
|
+
* are ever in flight, so the memory this costs is bounded by the two together whatever the file's
|
|
325
|
+
* size. An empty file is one empty part, so that the object exists.
|
|
326
|
+
*
|
|
327
|
+
* Attributes belong on the upload rather than added afterwards: completing an upload is finished off
|
|
328
|
+
* in the background, and the object row written at the end carries what this call supplied - an
|
|
329
|
+
* attribute added between here and there is overwritten and silently lost.
|
|
330
|
+
*
|
|
331
|
+
* @throws {EuclidServiceError} if a part or one of the calls bracketing them failed for good.
|
|
332
|
+
* @throws {Error} if `partSize` is less than a byte, which the server rejects too.
|
|
333
|
+
*/
|
|
334
|
+
uploadFile(bucketErn: string, key: string, file: string, options?: UploadOptions): Promise<StoredObject>;
|
|
335
|
+
/**
|
|
336
|
+
* Downloads an object to a local file, fetching its parts several at a time.
|
|
337
|
+
*
|
|
338
|
+
* An object that fits in one part skips multipart entirely. Unlike an upload - whose source this
|
|
339
|
+
* client has already stat'ed - a download's size is not known before asking, so the single-request
|
|
340
|
+
* path is tried first and HTTP 413 is what says the object was too large for it.
|
|
341
|
+
*
|
|
342
|
+
* Missing parent directories are created. Answers with the number of bytes written.
|
|
343
|
+
*
|
|
344
|
+
* @throws {Error} if `partSize` is less than a byte, which the server rejects too.
|
|
345
|
+
*/
|
|
346
|
+
downloadFile(bucketErn: string, key: string, file: string, options?: DownloadOptions): Promise<number>;
|
|
347
|
+
/**
|
|
348
|
+
* ESM's own metrics, as the server collects them. Answered unparsed - the shape belongs to the
|
|
349
|
+
* monitoring module rather than to ESM.
|
|
350
|
+
*/
|
|
351
|
+
metrics(): Promise<Record<string, unknown>>;
|
|
352
|
+
/**
|
|
353
|
+
* The byte-carrying actions, on this client's transfer timeout rather than the session's - a 5 MiB
|
|
354
|
+
* part on a slow link is not an action that answers from a database.
|
|
355
|
+
*/
|
|
356
|
+
protected postBytes(action: string, data: Bytes, headers?: Record<string, string>, timeoutMs?: number): Promise<Response>;
|
|
357
|
+
}
|
|
358
|
+
//# sourceMappingURL=esm.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"esm.d.ts","sourceRoot":"","sources":["../../src/modules/esm.ts"],"names":[],"mappings":"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"}
|