@deveye/types 0.20.3 → 0.21.1
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/package.json +1 -1
- package/src/domain/admission.ts +37 -0
- package/src/domain/device.ts +7 -3
- package/src/domain/featureRegistry.ts +3 -2
- package/src/domain/maintenance.ts +7 -1
- package/src/domain/notifications.ts +16 -0
- package/src/domain/packages.ts +34 -2
- package/src/domain/report.ts +15 -3
- package/src/domain/secrecy.ts +13 -0
- package/src/domain/user.ts +10 -1
- package/src/features/admin.ts +59 -1
- package/src/features/debug.ts +372 -0
- package/src/features/registry.ts +2 -0
- package/src/features/user.ts +46 -0
- package/src/http/auth.ts +2 -0
- package/src/http/device.ts +33 -15
- package/src/http/status.ts +6 -0
- package/src/index.ts +125 -6
- package/src/protocol/agent.ts +127 -5
- package/src/protocol/error.ts +4 -1
- package/src/sdk/accountExport.test.ts +115 -0
- package/src/sdk/accountExport.ts +254 -0
- package/src/sdk/client-ambient.d.ts +86 -0
- package/src/sdk/client.ts +44 -0
- package/src/sdk/devb.test.ts +148 -0
- package/src/sdk/devb.ts +146 -0
- package/src/sdk/download.test.ts +40 -0
- package/src/sdk/download.ts +48 -0
- package/src/sdk/manifest.test.ts +17 -1
- package/src/sdk/manifest.ts +51 -11
- package/src/sdk/net.test.ts +42 -1
- package/src/sdk/net.ts +100 -2
- package/src/sdk/pool.test.ts +36 -0
- package/src/sdk/pool.ts +26 -0
- package/src/sdk/providers.ts +107 -11
- package/src/sdk/server.ts +402 -13
- package/src/sdk/testing.test.ts +66 -0
- package/src/sdk/testing.ts +222 -2
package/src/sdk/server.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import type { Duplex } from 'node:stream';
|
|
2
|
+
import type { FeatureAccountExport } from './accountExport';
|
|
1
3
|
import type { ItemTree, ItemTreeRows } from './copy';
|
|
2
4
|
import type { z, ZodType } from 'zod';
|
|
3
5
|
import type { ErrorCode } from '../protocol/error';
|
|
@@ -11,6 +13,7 @@ import type { AgentManifest } from '../http/device';
|
|
|
11
13
|
import type { MetricSnapshot } from '../domain/metrics';
|
|
12
14
|
import type { UserColor } from '../domain/user';
|
|
13
15
|
import type { SdkDnsRecord } from './domains';
|
|
16
|
+
import type { MailTransportMessage } from './providers';
|
|
14
17
|
import type { ModuleEnvSpec } from './env';
|
|
15
18
|
import type {
|
|
16
19
|
AgentSyncAckPayload,
|
|
@@ -26,6 +29,7 @@ import type {
|
|
|
26
29
|
AgentSyncMovePayload,
|
|
27
30
|
AgentSyncOpResultPayload,
|
|
28
31
|
AgentSyncPushPayload,
|
|
32
|
+
AgentSyncPushAckPayload,
|
|
29
33
|
AgentSyncScanPayload,
|
|
30
34
|
AgentFilesMutatePayload,
|
|
31
35
|
AgentFilesUploadPayload,
|
|
@@ -34,7 +38,15 @@ import type {
|
|
|
34
38
|
CloudSyncStatePush
|
|
35
39
|
} from '../protocol/agent';
|
|
36
40
|
|
|
37
|
-
export {
|
|
41
|
+
export {
|
|
42
|
+
isPublicIp,
|
|
43
|
+
isSafePublicUrl,
|
|
44
|
+
NetRefused,
|
|
45
|
+
resolvesPublicly,
|
|
46
|
+
safeFetchText,
|
|
47
|
+
type SafeFetchOptions
|
|
48
|
+
} from './net';
|
|
49
|
+
export { mapLimit } from './pool';
|
|
38
50
|
export {
|
|
39
51
|
defineModuleEnv,
|
|
40
52
|
MODULE_ENV_NAME_PATTERN,
|
|
@@ -302,6 +314,21 @@ export interface DevEyeFacade {
|
|
|
302
314
|
/** The CALLER's own account, never someone else's. */
|
|
303
315
|
me(): Promise<SdkAccount>;
|
|
304
316
|
};
|
|
317
|
+
/** Requires capability `'accounts.usage'`. */
|
|
318
|
+
usage: {
|
|
319
|
+
/**
|
|
320
|
+
* What this account uses of every limit this DevEye knows. The caller
|
|
321
|
+
* must be this account or a global administrator (`forbidden`
|
|
322
|
+
* otherwise); an unknown account throws `not_found`.
|
|
323
|
+
*/
|
|
324
|
+
of(userId: number): Promise<SdkAccountUsage>;
|
|
325
|
+
/**
|
|
326
|
+
* `of` for many accounts, in the order given, unknown ids left out. A
|
|
327
|
+
* global administrator's surface only. The host paces the counting so a
|
|
328
|
+
* sweep never starves the database: one call, never one per account.
|
|
329
|
+
*/
|
|
330
|
+
ofMany(userIds: readonly number[]): Promise<readonly SdkAccountUsage[]>;
|
|
331
|
+
};
|
|
305
332
|
}
|
|
306
333
|
|
|
307
334
|
/** An account of this DevEye, as `'accounts.read'` shows it. */
|
|
@@ -311,6 +338,14 @@ export interface SdkAccount {
|
|
|
311
338
|
username: string;
|
|
312
339
|
/** A global administrator of this DevEye. */
|
|
313
340
|
isAdmin: boolean;
|
|
341
|
+
/**
|
|
342
|
+
* A throwaway account the app's end-to-end runner created and will delete:
|
|
343
|
+
* never a person, and its address receives nothing. Check this, never the
|
|
344
|
+
* address: it is set once, at creation, and nothing can grant it later.
|
|
345
|
+
*/
|
|
346
|
+
e2e: boolean;
|
|
347
|
+
/** Suspended by an administrator: it keeps everything and cannot sign in. */
|
|
348
|
+
suspended: boolean;
|
|
314
349
|
/** Milliseconds since the epoch. */
|
|
315
350
|
created: number;
|
|
316
351
|
}
|
|
@@ -327,6 +362,79 @@ export interface SdkAccounts {
|
|
|
327
362
|
* and is capped at 50.
|
|
328
363
|
*/
|
|
329
364
|
search(query: string, limit?: number): Promise<readonly SdkAccount[]>;
|
|
365
|
+
/** Every account, oldest first: an administrator's sweep. What you show of it is yours to gate. */
|
|
366
|
+
all(): Promise<readonly SdkAccount[]>;
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/** What one account uses of one limit, whatever its plan allows. */
|
|
370
|
+
export interface SdkAccountQuotaUse {
|
|
371
|
+
/**
|
|
372
|
+
* `stock`: things that exist, the excess paused; `flow`: checked at each
|
|
373
|
+
* use, nothing paused; `perOperation`: one operation bounded, nothing counted.
|
|
374
|
+
*/
|
|
375
|
+
kind: 'stock' | 'flow' | 'perOperation';
|
|
376
|
+
/**
|
|
377
|
+
* What the limit is compared to now, over every workspace the account
|
|
378
|
+
* OWNS: the things that exist, paused ones included, for a `stock`; this
|
|
379
|
+
* month's flow or the bytes held otherwise; for `workspace.members`, its
|
|
380
|
+
* fullest shared workspace. `null` for a `perOperation` limit.
|
|
381
|
+
*/
|
|
382
|
+
used: number | null;
|
|
383
|
+
/** How many of them its plan holds paused, in the unit of `used`. 0 for anything but a stock. */
|
|
384
|
+
paused: number;
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
/** What one account uses, as `'accounts.usage'` reads it. */
|
|
388
|
+
export interface SdkAccountUsage {
|
|
389
|
+
userId: number;
|
|
390
|
+
/**
|
|
391
|
+
* By `<featureId>.<quotaKey>`: every quota of the installed modules and the
|
|
392
|
+
* host's own (`workspace.shared`, `workspace.members`, `domains.hosts`),
|
|
393
|
+
* bounded or not. The limits are the plan provider's (`planFor`).
|
|
394
|
+
*/
|
|
395
|
+
quotas: Readonly<Record<string, SdkAccountQuotaUse>>;
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
/**
|
|
399
|
+
* Any account's usage, sessionless (capability `'accounts.usage'`), for
|
|
400
|
+
* services: the same reading as `ctx.deveye.usage`, without its caller check.
|
|
401
|
+
*/
|
|
402
|
+
export interface SdkUsage {
|
|
403
|
+
of(userId: number): Promise<SdkAccountUsage>;
|
|
404
|
+
ofMany(userIds: readonly number[]): Promise<readonly SdkAccountUsage[]>;
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
/** One email to an account. Plain text everywhere: the host lays it out and escapes it. */
|
|
408
|
+
export interface SdkAccountMailMessage {
|
|
409
|
+
subject: string;
|
|
410
|
+
/** One paragraph each, in order. */
|
|
411
|
+
paragraphs: readonly string[];
|
|
412
|
+
/** Framed and set apart after the paragraphs: what the reader must not miss (a deadline). */
|
|
413
|
+
notice?: string;
|
|
414
|
+
/** A link drawn as a button, after the notice. */
|
|
415
|
+
button?: { label: string; url: string };
|
|
416
|
+
/** Small print, last. */
|
|
417
|
+
footnote?: string;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
/** Emails to the accounts of this DevEye, from the server's own sender (capability `'accounts.mail'`). */
|
|
421
|
+
export interface SdkAccountMail {
|
|
422
|
+
/** `false` when this server has no mail transport: `send` would throw `conflict`. */
|
|
423
|
+
readonly configured: boolean;
|
|
424
|
+
/**
|
|
425
|
+
* Sends to the account's own address, never another, and resolves that
|
|
426
|
+
* address for your records. Throws `not_found` for an unknown account and
|
|
427
|
+
* `conflict` without a transport; a refusal of the mail server rejects as
|
|
428
|
+
* is. Nothing is retried for you.
|
|
429
|
+
*/
|
|
430
|
+
send(userId: number, message: SdkAccountMailMessage): Promise<string>;
|
|
431
|
+
/**
|
|
432
|
+
* One copy to each active administrator of this DevEye, for what only the
|
|
433
|
+
* operator can act on (a report of illicit content). Resolves the addresses
|
|
434
|
+
* reached, empty when there is no active administrator. Every address is
|
|
435
|
+
* tried; the first refusal then rejects. Throws `conflict` without a transport.
|
|
436
|
+
*/
|
|
437
|
+
sendToAdmins(message: SdkAccountMailMessage): Promise<readonly string[]>;
|
|
330
438
|
}
|
|
331
439
|
|
|
332
440
|
/**
|
|
@@ -348,6 +456,13 @@ export interface SdkPlanPauses {
|
|
|
348
456
|
paused(key: string): readonly string[];
|
|
349
457
|
}
|
|
350
458
|
|
|
459
|
+
/** Where the owner stands against one limit of YOUR `manifest.quotas`. */
|
|
460
|
+
export interface SdkQuotaUse {
|
|
461
|
+
/** By YOUR `server.quotas[key]`, over every workspace the owner owns. */
|
|
462
|
+
used: number;
|
|
463
|
+
limit: number;
|
|
464
|
+
}
|
|
465
|
+
|
|
351
466
|
/**
|
|
352
467
|
* What the account's plan allows of YOUR `manifest.quotas`. The account is the
|
|
353
468
|
* OWNER of the workspace of the call: in a shared workspace, what a member
|
|
@@ -355,24 +470,41 @@ export interface SdkPlanPauses {
|
|
|
355
470
|
* everything is unlimited.
|
|
356
471
|
*/
|
|
357
472
|
export interface SdkQuota extends SdkPlanPauses {
|
|
358
|
-
/**
|
|
473
|
+
/**
|
|
474
|
+
* `null` = unlimited. An undeclared key throws `validation`. Reads 0 while
|
|
475
|
+
* the host serves priority accounts first and the owner is not one.
|
|
476
|
+
*/
|
|
359
477
|
limit(key: string): Promise<number | null>;
|
|
360
478
|
/**
|
|
361
479
|
* Call it BEFORE creating. `countAfter` receives the ids of every workspace
|
|
362
480
|
* the owner account owns and returns how many there would be once created;
|
|
363
481
|
* it is never called when unlimited. Throws `quota_exceeded` beyond the
|
|
364
|
-
* limit.
|
|
482
|
+
* limit. Count with the same repo function as `server.quotas[key]`: the
|
|
483
|
+
* usage shown and the refusal must agree.
|
|
365
484
|
*/
|
|
366
485
|
assert(
|
|
367
486
|
key: string,
|
|
368
487
|
countAfter: (ownerWorkspaceIds: readonly number[]) => Promise<number>
|
|
369
488
|
): Promise<void>;
|
|
489
|
+
/**
|
|
490
|
+
* Where the owner stands, counted by YOUR `server.quotas[key]`: what a
|
|
491
|
+
* screen says BEFORE the refusal. `null` = unlimited, and nothing is
|
|
492
|
+
* counted. A `perOperation` key throws `validation`: nothing accumulates.
|
|
493
|
+
*/
|
|
494
|
+
usage(key: string): Promise<SdkQuotaUse | null>;
|
|
370
495
|
/**
|
|
371
496
|
* Call it before running a `stock` item on demand (check now, deploy now,
|
|
372
497
|
* open a session): throws `quota_exceeded` when its owner's plan holds it
|
|
373
498
|
* paused, which opens the plan prompt on the client.
|
|
374
499
|
*/
|
|
375
500
|
assertActive(key: string, itemId: string): Promise<void>;
|
|
501
|
+
/**
|
|
502
|
+
* Whether the owner pays: a paid or trial plan, a plan granted on the paid
|
|
503
|
+
* tier, an administrator, or no plan provider at all (a self-hosted
|
|
504
|
+
* instance). What a default that costs the host keys on (a probe cadence),
|
|
505
|
+
* never a refusal: refusals go through `limit` and `assert`.
|
|
506
|
+
*/
|
|
507
|
+
paid(): Promise<boolean>;
|
|
376
508
|
}
|
|
377
509
|
|
|
378
510
|
/** One item a `stock` quota counts. */
|
|
@@ -393,14 +525,24 @@ export interface SdkPlanPauseChange {
|
|
|
393
525
|
resumed: readonly SdkStockItem[];
|
|
394
526
|
}
|
|
395
527
|
|
|
396
|
-
/**
|
|
397
|
-
|
|
528
|
+
/**
|
|
529
|
+
* How the host counts one of your quotas, for `ctx.quota.usage` and an
|
|
530
|
+
* account's usage (`'accounts.usage'`): a `stock` by its list, any other by
|
|
531
|
+
* its count, under the very WHERE of the counter you pass to `assert`.
|
|
532
|
+
*/
|
|
533
|
+
export interface FeatureQuotaEntry<Repo = unknown> {
|
|
398
534
|
/**
|
|
399
|
-
*
|
|
400
|
-
*
|
|
535
|
+
* `stock` quotas only, required there: the items the quota counts in these
|
|
536
|
+
* workspaces, OLDEST FIRST (creation, then id). How many is the usage; the
|
|
401
537
|
* host keeps the first `limit` running and pauses the rest.
|
|
402
538
|
*/
|
|
403
|
-
list(repo: Repo, ownerWorkspaceIds: readonly number[]): Promise<readonly SdkStockItem[]>;
|
|
539
|
+
list?(repo: Repo, ownerWorkspaceIds: readonly number[]): Promise<readonly SdkStockItem[]>;
|
|
540
|
+
/**
|
|
541
|
+
* Any other quota but `perOperation`, required there: what the limit is
|
|
542
|
+
* compared to now (this month's events, the bytes held). A month is the
|
|
543
|
+
* current UTC month unless your feature keeps a calendar of its own.
|
|
544
|
+
*/
|
|
545
|
+
count?(repo: Repo, ownerWorkspaceIds: readonly number[]): Promise<number>;
|
|
404
546
|
}
|
|
405
547
|
|
|
406
548
|
/** A workspace as the fleet sees it: enough to attach a device to it. */
|
|
@@ -447,9 +589,21 @@ export interface AgentsFacade {
|
|
|
447
589
|
* offline (it receives the config at its next connection anyway).
|
|
448
590
|
*/
|
|
449
591
|
pushConfig(deviceId: string): Promise<boolean>;
|
|
592
|
+
/**
|
|
593
|
+
* The cadence each device's agent runs at, by device id: its own setting,
|
|
594
|
+
* or the default of the plan of its HOME workspace's owner.
|
|
595
|
+
*/
|
|
596
|
+
metricIntervals(
|
|
597
|
+
devices: readonly {
|
|
598
|
+
id: string;
|
|
599
|
+
workspace_id: number | null;
|
|
600
|
+
metric_interval_seconds: number | null;
|
|
601
|
+
}[]
|
|
602
|
+
): Promise<ReadonlyMap<string, number>>;
|
|
450
603
|
requestSyncConfig(deviceId: string, payload: AgentSyncConfigPayload): boolean;
|
|
451
604
|
requestSyncScan(deviceId: string, payload: AgentSyncScanPayload): boolean;
|
|
452
605
|
requestSyncPush(deviceId: string, payload: AgentSyncPushPayload): boolean;
|
|
606
|
+
requestSyncPushAck(deviceId: string, payload: AgentSyncPushAckPayload): boolean;
|
|
453
607
|
requestSyncApplyChunk(deviceId: string, payload: AgentSyncApplyChunkPayload): boolean;
|
|
454
608
|
requestSyncApplyStart(deviceId: string, payload: AgentSyncApplyStartPayload): boolean;
|
|
455
609
|
requestSyncApplyDir(deviceId: string, payload: AgentSyncApplyDirPayload): boolean;
|
|
@@ -502,6 +656,19 @@ export interface AgentsFacade {
|
|
|
502
656
|
request: AgentFolderArchiveRequest,
|
|
503
657
|
options?: { signal?: AbortSignal }
|
|
504
658
|
): AgentFolderArchive;
|
|
659
|
+
/**
|
|
660
|
+
* A TCP connection opened BY THE DEVICE to `host:port` and relayed by its
|
|
661
|
+
* agent: a service only the machine can reach (a database on its
|
|
662
|
+
* loopback) becomes a stream here, read at the consumer's pace. The agent
|
|
663
|
+
* only reaches its own loopback, plus the hosts its operator lists in
|
|
664
|
+
* `tunnel_targets`, and refuses everything under `allow_tunnel = false`.
|
|
665
|
+
* Rejects with the reason (offline, refused, unreachable, an agent that
|
|
666
|
+
* predates the order: check `report.agent.probes` for
|
|
667
|
+
* `AGENT_TUNNEL_PROBE` first to say so plainly). Once open, the stream is
|
|
668
|
+
* destroyed with an error when the device goes offline; ending or
|
|
669
|
+
* destroying it closes the connection on the machine.
|
|
670
|
+
*/
|
|
671
|
+
openTcp(deviceId: string, target: { host: string; port: number }): Promise<Duplex>;
|
|
505
672
|
/**
|
|
506
673
|
* Bytes queued on the agent's socket, not yet on the wire. A sender that
|
|
507
674
|
* streams towards an agent must watch it: the socket accepts everything,
|
|
@@ -594,6 +761,58 @@ export interface SdkProviders {
|
|
|
594
761
|
get<T>(key: string): T | undefined;
|
|
595
762
|
}
|
|
596
763
|
|
|
764
|
+
/** One object of an {@link SdkObjectStore}, as `list` yields it. */
|
|
765
|
+
export interface SdkStoredObject {
|
|
766
|
+
key: string;
|
|
767
|
+
size: number;
|
|
768
|
+
}
|
|
769
|
+
|
|
770
|
+
/**
|
|
771
|
+
* Where a module keeps files (capability `'objects'`): the server's disk, or
|
|
772
|
+
* the S3 bucket the host configured. A key is a relative path (`a/b/c`, no
|
|
773
|
+
* `..`, no leading `/`); store only the KEY in your tables, never where it
|
|
774
|
+
* resolves, so the host can move the whole tree (another disk, another
|
|
775
|
+
* bucket) without a row to rewrite. Writes are atomic: a reader sees the
|
|
776
|
+
* whole object or none.
|
|
777
|
+
*/
|
|
778
|
+
export interface SdkObjectStore {
|
|
779
|
+
/** `'local'`: the server's disk. `'s3'`: every byte read costs egress. */
|
|
780
|
+
readonly kind: 'local' | 's3';
|
|
781
|
+
/** Where it lives, for a screen: « disque du serveur », « S3 : bucket ». */
|
|
782
|
+
describe(): string;
|
|
783
|
+
put(key: string, body: AsyncIterable<Uint8Array> | Uint8Array): Promise<{ size: number }>;
|
|
784
|
+
/**
|
|
785
|
+
* Stores a finished local file under `key`, then removes the local file:
|
|
786
|
+
* a rename on the server's disk, an upload on S3. For a file assembled
|
|
787
|
+
* in {@link spoolDir}.
|
|
788
|
+
*/
|
|
789
|
+
putFile(key: string, localPath: string): Promise<{ size: number }>;
|
|
790
|
+
/** The object's bytes, streamed. `range` is inclusive, like HTTP's. Throws when absent. */
|
|
791
|
+
get(key: string, range?: { start: number; end?: number }): AsyncIterable<Buffer>;
|
|
792
|
+
/** `null` when absent. */
|
|
793
|
+
head(key: string): Promise<{ size: number } | null>;
|
|
794
|
+
/** Every object whose key starts with `prefix`, in no guaranteed order. */
|
|
795
|
+
list(prefix: string): AsyncIterable<SdkStoredObject>;
|
|
796
|
+
/** Idempotent: an absent key is not an error. */
|
|
797
|
+
delete(key: string): Promise<void>;
|
|
798
|
+
/** Every object under `prefix`, which must end with `/`. */
|
|
799
|
+
deletePrefix(prefix: string): Promise<void>;
|
|
800
|
+
/**
|
|
801
|
+
* A directory on the server's disk, whatever `kind`, for what cannot be
|
|
802
|
+
* written as a whole object at once (a partial upload resumed later).
|
|
803
|
+
* Yours alone; the store never cleans it.
|
|
804
|
+
*/
|
|
805
|
+
spoolDir(): string;
|
|
806
|
+
/**
|
|
807
|
+
* The store's root when files written there would not last: on the
|
|
808
|
+
* server's disk, inside a container, a directory on no mounted volume,
|
|
809
|
+
* so its writable layer, wiped at the next redeploy. `null` otherwise,
|
|
810
|
+
* and always on S3. Refuse to write there, naming the variable that sets
|
|
811
|
+
* `localDir`: the files would vanish without a word.
|
|
812
|
+
*/
|
|
813
|
+
ephemeralRoot(): Promise<string | null>;
|
|
814
|
+
}
|
|
815
|
+
|
|
597
816
|
/**
|
|
598
817
|
* Raw bytes under the SERVER key, for wrapping module-owned key material; never
|
|
599
818
|
* for user data, which goes through ciphers and the store. The host seals under
|
|
@@ -632,6 +851,8 @@ export interface SdkDevice {
|
|
|
632
851
|
workspaceId: number | null;
|
|
633
852
|
/** The agent's metric cadence in seconds, null when it follows the default. */
|
|
634
853
|
metricIntervalSeconds: number | null;
|
|
854
|
+
/** The cadence the agent actually runs at: its own, or the default of its owner's plan. */
|
|
855
|
+
effectiveMetricIntervalSeconds: number;
|
|
635
856
|
/** The last OS/security report, null before the first one (or unreadable). */
|
|
636
857
|
report: DeviceReport | null;
|
|
637
858
|
}
|
|
@@ -1159,8 +1380,33 @@ export interface FeatureService {
|
|
|
1159
1380
|
* rows go with the account (`ON DELETE CASCADE`), nothing to do for them.
|
|
1160
1381
|
* Runs before the row is deleted: a throw aborts the deletion. Never called
|
|
1161
1382
|
* while your service is halted by maintenance: the deletion is refused then.
|
|
1383
|
+
* Return a note when the holder must learn something of yours (their
|
|
1384
|
+
* subscription stopped): it joins the confirmation email they receive.
|
|
1385
|
+
*/
|
|
1386
|
+
onAccountDeleted?(
|
|
1387
|
+
userId: number
|
|
1388
|
+
): void | SdkAccountDeletedNote | Promise<void | SdkAccountDeletedNote>;
|
|
1389
|
+
/**
|
|
1390
|
+
* What your service knows of its own health that the host cannot see: a
|
|
1391
|
+
* port it failed to open, an engine it depends on. Read by the public
|
|
1392
|
+
* status page about once a minute. Answer from memory: no network call, no
|
|
1393
|
+
* write, no heavy query; after 2 s the host counts you as degraded. Omit it
|
|
1394
|
+
* when the process and the database are all you rely on: the host already
|
|
1395
|
+
* watches those, along with your failing tickers and commands.
|
|
1162
1396
|
*/
|
|
1163
|
-
|
|
1397
|
+
health?(): SdkServiceHealth | Promise<SdkServiceHealth>;
|
|
1398
|
+
}
|
|
1399
|
+
|
|
1400
|
+
/** A service's own verdict on itself, as `FeatureService.health` gives it. */
|
|
1401
|
+
export interface SdkServiceHealth {
|
|
1402
|
+
state: 'up' | 'degraded' | 'down';
|
|
1403
|
+
/** Shown on the public status page: a short sentence for users, never an internal detail. */
|
|
1404
|
+
reason?: string;
|
|
1405
|
+
}
|
|
1406
|
+
|
|
1407
|
+
/** One paragraph of yours in the email confirming an account's deletion to its holder. */
|
|
1408
|
+
export interface SdkAccountDeletedNote {
|
|
1409
|
+
paragraph: string;
|
|
1164
1410
|
}
|
|
1165
1411
|
|
|
1166
1412
|
/**
|
|
@@ -1184,6 +1430,10 @@ export interface FeatureServiceDeps<Repo = unknown> {
|
|
|
1184
1430
|
devices: SdkFleetDevices;
|
|
1185
1431
|
/** Capability `'accounts.read'`. */
|
|
1186
1432
|
accounts: SdkAccounts;
|
|
1433
|
+
/** Capability `'accounts.usage'`. */
|
|
1434
|
+
usage: SdkUsage;
|
|
1435
|
+
/** Capability `'accounts.mail'`. */
|
|
1436
|
+
accountMail: SdkAccountMail;
|
|
1187
1437
|
/**
|
|
1188
1438
|
* {@link SdkQuota} for a workspace, sessionless: for what gets created
|
|
1189
1439
|
* outside any command (bytes an agent uploads). Same account rule, the
|
|
@@ -1234,6 +1484,12 @@ export interface FeatureServiceDeps<Repo = unknown> {
|
|
|
1234
1484
|
};
|
|
1235
1485
|
/** Raw key wrapping under the server key, and derived keys. */
|
|
1236
1486
|
keys: SdkServerKeys;
|
|
1487
|
+
/**
|
|
1488
|
+
* The object store (capability `'objects'`). `localDir` is where your
|
|
1489
|
+
* objects live while the host keeps them on its disk, typically a path of
|
|
1490
|
+
* your `env`; with an S3 configured, it only holds your `spoolDir()`.
|
|
1491
|
+
*/
|
|
1492
|
+
objects(localDir: string): SdkObjectStore;
|
|
1237
1493
|
/** Redeems a ticket minted by `ctx.secrecy.ticket` of THIS module; `null` when invalid, expired or another module's. */
|
|
1238
1494
|
secrecy: { redeem(ticket: string): Promise<SdkRedeemedTicket | null> };
|
|
1239
1495
|
/** Where DevEye lives (the same `origins` a request context gets): for a page or a link a route hands to the browser. */
|
|
@@ -1275,14 +1531,131 @@ export interface FeatureServer<Repo = unknown> {
|
|
|
1275
1531
|
items?: FeatureItemsEntry<Repo>;
|
|
1276
1532
|
/** Required when the manifest declares `domains`, refused otherwise. */
|
|
1277
1533
|
domains?: FeatureDomainsEntry<Repo>;
|
|
1278
|
-
/**
|
|
1279
|
-
|
|
1534
|
+
/**
|
|
1535
|
+
* What the holder's data export writes of your feature (GDPR
|
|
1536
|
+
* portability): see {@link FeatureAccountExport}. Required once your
|
|
1537
|
+
* feature owns a table; without tables, the host exports your store alone.
|
|
1538
|
+
*/
|
|
1539
|
+
accountExport?: FeatureAccountExport<Repo>;
|
|
1540
|
+
/** One entry per quota of the manifest, by its key, `perOperation` ones excepted, and none other. */
|
|
1541
|
+
quotas?: Readonly<Record<string, FeatureQuotaEntry<Repo>>>;
|
|
1280
1542
|
/**
|
|
1281
1543
|
* The environment variables you read, as the spec you read them with
|
|
1282
1544
|
* (`defineModuleEnv`). Plain data: the host reads it again at boot and
|
|
1283
1545
|
* warns about every variable left to its default.
|
|
1284
1546
|
*/
|
|
1285
1547
|
env?: ModuleEnvSpec;
|
|
1548
|
+
/**
|
|
1549
|
+
* Every email you send, on made-up data, for the administrator's mail
|
|
1550
|
+
* tester: built by the SAME function as the real one, or the tester proves
|
|
1551
|
+
* nothing. `sender: 'server'` requires capability `'accounts.mail'`. Keys
|
|
1552
|
+
* are unique within your feature.
|
|
1553
|
+
*/
|
|
1554
|
+
mailSamples?: readonly SdkMailSample[];
|
|
1555
|
+
/** Your end-to-end scenarios, run by an administrator against this very server. */
|
|
1556
|
+
e2e?: FeatureE2eEntry<Repo>;
|
|
1557
|
+
}
|
|
1558
|
+
|
|
1559
|
+
/** What a mail sample is built with. */
|
|
1560
|
+
export interface SdkMailSampleContext {
|
|
1561
|
+
origins: SdkOrigins;
|
|
1562
|
+
/** Milliseconds since the epoch. */
|
|
1563
|
+
now: number;
|
|
1564
|
+
}
|
|
1565
|
+
|
|
1566
|
+
/** A message a workspace mailbox sends: what `MailTransportProvider.send` takes, the recipient aside. */
|
|
1567
|
+
export type SdkWorkspaceMail = Omit<MailTransportMessage, 'to'>;
|
|
1568
|
+
|
|
1569
|
+
export type SdkMailSample = {
|
|
1570
|
+
/** `[a-z][a-zA-Z0-9]*`, unique within your feature. */
|
|
1571
|
+
key: string;
|
|
1572
|
+
/** What the tester lists, in the interface's language. */
|
|
1573
|
+
label: string;
|
|
1574
|
+
} & (
|
|
1575
|
+
| {
|
|
1576
|
+
/** From the server's own sender, as `accountMail.send` would. */
|
|
1577
|
+
sender: 'server';
|
|
1578
|
+
build(ctx: SdkMailSampleContext): SdkAccountMailMessage | Promise<SdkAccountMailMessage>;
|
|
1579
|
+
}
|
|
1580
|
+
| {
|
|
1581
|
+
/** From a workspace mailbox the administrator picks, as `MAIL_TRANSPORT_PROVIDER` would. */
|
|
1582
|
+
sender: 'workspace';
|
|
1583
|
+
build(ctx: SdkMailSampleContext): SdkWorkspaceMail | Promise<SdkWorkspaceMail>;
|
|
1584
|
+
}
|
|
1585
|
+
);
|
|
1586
|
+
|
|
1587
|
+
/** The throwaway account a scenario runs as. It owns `workspaceId` and is deleted with all it owns afterwards. */
|
|
1588
|
+
export interface SdkE2eAccount {
|
|
1589
|
+
userId: number;
|
|
1590
|
+
username: string;
|
|
1591
|
+
email: string;
|
|
1592
|
+
password: string;
|
|
1593
|
+
/** Its personal workspace. */
|
|
1594
|
+
workspaceId: number;
|
|
1595
|
+
}
|
|
1596
|
+
|
|
1597
|
+
export interface SdkE2eContext<Repo = unknown> {
|
|
1598
|
+
account: SdkE2eAccount;
|
|
1599
|
+
/**
|
|
1600
|
+
* A command through a real socket of that account and the whole
|
|
1601
|
+
* dispatcher. Rejects with a `FeatureError` carrying the server's code.
|
|
1602
|
+
*/
|
|
1603
|
+
send<T = unknown>(command: string, input: unknown, opts?: { workspaceId?: number }): Promise<T>;
|
|
1604
|
+
/** A sessionless request to this server's own listener: what a visitor's browser sends to a public route. */
|
|
1605
|
+
fetch(
|
|
1606
|
+
path: string,
|
|
1607
|
+
init?: { method?: 'GET' | 'POST'; headers?: Record<string, string>; body?: string }
|
|
1608
|
+
): Promise<{ status: number; body: string }>;
|
|
1609
|
+
/**
|
|
1610
|
+
* Polls until `probe` answers something other than `null`, `undefined` or
|
|
1611
|
+
* `false`, then resolves with it. Rejects after `timeoutMs` (default 10 s),
|
|
1612
|
+
* saying `what` was awaited.
|
|
1613
|
+
*/
|
|
1614
|
+
waitFor<T>(
|
|
1615
|
+
probe: () => Promise<T | null | undefined | false>,
|
|
1616
|
+
opts?: { timeoutMs?: number; intervalMs?: number; what?: string }
|
|
1617
|
+
): Promise<T>;
|
|
1618
|
+
/**
|
|
1619
|
+
* Undoes something once the steps are over, whatever happened, last
|
|
1620
|
+
* registered first, while the account still exists. Register the undo
|
|
1621
|
+
* right after the thing is created, before anything can fail.
|
|
1622
|
+
*/
|
|
1623
|
+
defer(label: string, undo: () => Promise<void>): void;
|
|
1624
|
+
/** Shared between the steps of one run. */
|
|
1625
|
+
state: Map<string, unknown>;
|
|
1626
|
+
repo: Repo;
|
|
1627
|
+
origins: SdkOrigins;
|
|
1628
|
+
/** Aborted when the administrator stops the run or a timeout fires. */
|
|
1629
|
+
signal: AbortSignal;
|
|
1630
|
+
}
|
|
1631
|
+
|
|
1632
|
+
export interface SdkE2eStep<Repo = unknown> {
|
|
1633
|
+
/** What the report shows, in the interface's language. */
|
|
1634
|
+
label: string;
|
|
1635
|
+
/** Longer than the default 20 s: a step that waits on a third party (a payment provider's webhook). */
|
|
1636
|
+
timeoutMs?: number;
|
|
1637
|
+
/** Throws to fail. A returned string is shown as the step's detail. */
|
|
1638
|
+
run(ctx: SdkE2eContext<Repo>): Promise<string | void>;
|
|
1639
|
+
}
|
|
1640
|
+
|
|
1641
|
+
export interface SdkE2eScenario<Repo = unknown> {
|
|
1642
|
+
/** `[a-z][a-zA-Z0-9]*`, unique within your feature. */
|
|
1643
|
+
id: string;
|
|
1644
|
+
label: string;
|
|
1645
|
+
/** Why it cannot run here right now, or `null`. Asked before every run. */
|
|
1646
|
+
skip?(ctx: { origins: SdkOrigins }): string | null | Promise<string | null>;
|
|
1647
|
+
steps: readonly SdkE2eStep<Repo>[];
|
|
1648
|
+
}
|
|
1649
|
+
|
|
1650
|
+
export interface FeatureE2eEntry<Repo = unknown> {
|
|
1651
|
+
scenarios: readonly SdkE2eScenario<Repo>[];
|
|
1652
|
+
/**
|
|
1653
|
+
* Removes what a crashed run left OUTSIDE the test accounts (an object at
|
|
1654
|
+
* a payment provider): what lives in your tables goes with the account.
|
|
1655
|
+
* Called at boot, before and after every run. Idempotent; a throw keeps
|
|
1656
|
+
* the run marked as leaving residue.
|
|
1657
|
+
*/
|
|
1658
|
+
sweep?(): Promise<void>;
|
|
1286
1659
|
}
|
|
1287
1660
|
|
|
1288
1661
|
/**
|
|
@@ -1610,7 +1983,18 @@ export type {
|
|
|
1610
1983
|
ItemTreeTable
|
|
1611
1984
|
} from './copy';
|
|
1612
1985
|
|
|
1613
|
-
|
|
1986
|
+
export { accountExportProblem, EXPORT_SECRET_COLUMN, exportTableRows } from './accountExport';
|
|
1987
|
+
export type {
|
|
1988
|
+
FeatureAccountExport,
|
|
1989
|
+
SdkAccountExportContext,
|
|
1990
|
+
SdkExportFiles,
|
|
1991
|
+
SdkExportSkip,
|
|
1992
|
+
SdkExportTable,
|
|
1993
|
+
SdkExportWriter,
|
|
1994
|
+
SdkWorkspaceExportContext
|
|
1995
|
+
} from './accountExport';
|
|
1996
|
+
|
|
1997
|
+
// Le conteneur chiffré des modules qui stockent des fichiers (voir `devb.ts`).
|
|
1614
1998
|
export {
|
|
1615
1999
|
BLOB_CHUNK_BYTES,
|
|
1616
2000
|
BLOB_CHUNK_SEALED,
|
|
@@ -1620,7 +2004,12 @@ export {
|
|
|
1620
2004
|
BLOB_VERSION_STREAM,
|
|
1621
2005
|
createBlobHeader,
|
|
1622
2006
|
openChunk,
|
|
2007
|
+
openSealedRange,
|
|
2008
|
+
openSealedStream,
|
|
1623
2009
|
openStreamDecipher,
|
|
1624
2010
|
parseBlobHeader,
|
|
1625
|
-
sealChunk
|
|
2011
|
+
sealChunk,
|
|
2012
|
+
sealedSize,
|
|
2013
|
+
sealStream
|
|
1626
2014
|
} from './devb';
|
|
2015
|
+
export { contentDisposition, parseByteRange } from './download';
|
package/src/sdk/testing.test.ts
CHANGED
|
@@ -80,6 +80,8 @@ test('the harness searches accounts like the app: substring, exact id first, cap
|
|
|
80
80
|
username,
|
|
81
81
|
email: `${username}@example.com`,
|
|
82
82
|
isAdmin: false,
|
|
83
|
+
e2e: false,
|
|
84
|
+
suspended: false,
|
|
83
85
|
created: 0
|
|
84
86
|
});
|
|
85
87
|
const { accounts } = createTestServiceDeps({
|
|
@@ -94,6 +96,10 @@ test('the harness searches accounts like the app: substring, exact id first, cap
|
|
|
94
96
|
assert.deepEqual(await ids('12abc'), []);
|
|
95
97
|
assert.deepEqual(await ids('', 1), [12]);
|
|
96
98
|
assert.equal((await ids('', 0)).length, 1, 'a limit below one is raised to one');
|
|
99
|
+
assert.deepEqual(
|
|
100
|
+
(await accounts.all()).map((a) => a.id),
|
|
101
|
+
[7, 12, 3]
|
|
102
|
+
);
|
|
97
103
|
});
|
|
98
104
|
|
|
99
105
|
test('the harness scopes domains to the workspace, and finds a host whatever its spelling', async () => {
|
|
@@ -144,6 +150,66 @@ test('the harness bounds a quota like the app: never counted when unlimited, ref
|
|
|
144
150
|
assert.deepEqual(bounded.recorded.accountChanges, [7]);
|
|
145
151
|
});
|
|
146
152
|
|
|
153
|
+
test('the harness reads usage like the app: nothing counted when unlimited, a stock by its list', async () => {
|
|
154
|
+
let counted = 0;
|
|
155
|
+
const quotas = {
|
|
156
|
+
monitors: {
|
|
157
|
+
list: (_repo: undefined, owned: readonly number[]) => {
|
|
158
|
+
counted++;
|
|
159
|
+
return Promise.resolve(owned.map((id) => ({ id: String(id), workspaceId: id })));
|
|
160
|
+
}
|
|
161
|
+
},
|
|
162
|
+
events: {
|
|
163
|
+
count: (_repo: undefined, owned: readonly number[]) => {
|
|
164
|
+
counted++;
|
|
165
|
+
return Promise.resolve(owned.length * 10);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
};
|
|
169
|
+
assert.equal(await createTestContext({ quotas }).quota.usage('monitors'), null);
|
|
170
|
+
assert.equal(counted, 0);
|
|
171
|
+
|
|
172
|
+
const ctx = createTestContext({
|
|
173
|
+
quotas,
|
|
174
|
+
quotaLimits: { monitors: 0, events: 50 },
|
|
175
|
+
ownerWorkspaceIds: [1, 2]
|
|
176
|
+
});
|
|
177
|
+
assert.deepEqual(await ctx.quota.usage('monitors'), { used: 2, limit: 0 });
|
|
178
|
+
assert.deepEqual(await ctx.quota.usage('events'), { used: 20, limit: 50 });
|
|
179
|
+
assert.deepEqual(
|
|
180
|
+
await createTestServiceDeps({ quotas, quotaLimits: { events: 5 } })
|
|
181
|
+
.quotaFor(1)
|
|
182
|
+
.usage('events'),
|
|
183
|
+
{ used: 10, limit: 5 }
|
|
184
|
+
);
|
|
185
|
+
await assert.rejects(
|
|
186
|
+
createTestContext({ quotaLimits: { monitors: 1 } }).quota.usage('monitors'),
|
|
187
|
+
/pass your server's quotas/
|
|
188
|
+
);
|
|
189
|
+
});
|
|
190
|
+
|
|
191
|
+
test('the harness reads an account usage like the app: its own, or anyone for an administrator', async () => {
|
|
192
|
+
const accountUsage = [
|
|
193
|
+
{ userId: 1, quotas: { 'x.monitors': { kind: 'stock' as const, used: 2, paused: 0 } } },
|
|
194
|
+
{ userId: 2, quotas: { 'x.monitors': { kind: 'stock' as const, used: 9, paused: 4 } } }
|
|
195
|
+
];
|
|
196
|
+
const me = createTestContext({ userId: 1, accountUsage });
|
|
197
|
+
assert.equal((await me.deveye.usage.of(1)).quotas['x.monitors'].used, 2);
|
|
198
|
+
await assert.rejects(me.deveye.usage.of(2), { code: 'forbidden' });
|
|
199
|
+
await assert.rejects(me.deveye.usage.ofMany([1]), { code: 'forbidden' });
|
|
200
|
+
|
|
201
|
+
const admin = createTestContext({ userId: 1, isAdmin: true, accountUsage });
|
|
202
|
+
assert.deepEqual(
|
|
203
|
+
(await admin.deveye.usage.ofMany([2, 5, 1])).map((u) => u.userId),
|
|
204
|
+
[2, 1]
|
|
205
|
+
);
|
|
206
|
+
await assert.rejects(admin.deveye.usage.of(5), { code: 'not_found' });
|
|
207
|
+
assert.equal(
|
|
208
|
+
(await createTestServiceDeps({ accountUsage }).usage.of(2)).quotas['x.monitors'].paused,
|
|
209
|
+
4
|
|
210
|
+
);
|
|
211
|
+
});
|
|
212
|
+
|
|
147
213
|
test('the harnesses hold the plan pauses and refuse a paused item on demand', async () => {
|
|
148
214
|
const ctx = createTestContext({ pausedItems: { monitors: ['7'] } });
|
|
149
215
|
assert.equal(ctx.quota.isPaused('monitors', '7'), true);
|