@deveye/types 0.20.0 → 0.20.2

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.
@@ -1,9 +1,12 @@
1
1
  import type { ZodType } from 'zod';
2
2
  import type { ItemAccess } from '../domain/sharing';
3
+ import type { PathExclusion } from '../domain/pathExclusions';
3
4
  import { normaliseDomainHost } from './domains';
4
5
  import { resolveExtras, type FeatureManifest } from './manifest';
5
6
  import {
6
7
  FeatureError,
8
+ type AgentFolderArchive,
9
+ type AgentFolderArchiveSummary,
7
10
  type DevEyeFacade,
8
11
  type FeatureDomainsContext,
9
12
  type SdkDns,
@@ -15,6 +18,8 @@ import {
15
18
  type SdkDevice,
16
19
  type SdkFeatureContext,
17
20
  type SdkLogger,
21
+ type SdkOrigins,
22
+ type SdkPlanPauses,
18
23
  type SdkProviders,
19
24
  type SdkTelemetry,
20
25
  type SdkTelemetrySnapshot,
@@ -112,6 +117,13 @@ export interface RecordedCalls {
112
117
  audits: { action: string; description: string }[];
113
118
  /** Outbound agent frames, as `{ method, deviceId }` (payloads dropped for brevity). */
114
119
  agentRequests: { method: string; deviceId: string }[];
120
+ /** Folder archives asked through `agents.archiveFolder`, with what they cover. */
121
+ archiveRequests: {
122
+ deviceId: string;
123
+ path: string;
124
+ exclusions: readonly PathExclusion[];
125
+ oneFileSystem: boolean;
126
+ }[];
115
127
  /** Instants pinned through `telemetry.pinInstant`. */
116
128
  pinnedInstants: { deviceId: string; ts: number }[];
117
129
  /** Frames pushed through `live.publish`, in order. */
@@ -172,9 +184,22 @@ export function testDevice(over: Partial<SdkDevice> & { id: string }): SdkDevice
172
184
  };
173
185
  }
174
186
 
175
- function recordingDevices(devices: readonly SdkDevice[]): DevEyeFacade['devices'] {
187
+ function recordingDevices(
188
+ devices: readonly SdkDevice[],
189
+ refuseExtras: boolean | readonly string[] = false
190
+ ): DevEyeFacade['devices'] {
191
+ const refused = (id: string): boolean =>
192
+ refuseExtras === true || (Array.isArray(refuseExtras) && refuseExtras.includes(id));
176
193
  return {
177
- authorize: (id) => Promise.resolve(devices.find((d) => d.id === id) ?? testDevice({ id })),
194
+ authorize: (id, options) =>
195
+ refused(id) && (options?.extras?.length ?? 0) > 0
196
+ ? Promise.reject(
197
+ new FeatureError(
198
+ 'forbidden',
199
+ 'Cette permission ne vous est pas accordée sur cet élément'
200
+ )
201
+ )
202
+ : Promise.resolve(devices.find((d) => d.id === id) ?? testDevice({ id })),
178
203
  list: () => Promise.resolve([...devices]),
179
204
  isOnline: (id) => devices.find((d) => d.id === id)?.online ?? true
180
205
  };
@@ -194,7 +219,49 @@ function recordingTelemetry(
194
219
  };
195
220
  }
196
221
 
197
- function recordingAgents(recorded: RecordedCalls): DevEyeFacade['agents'] {
222
+ /** What a test says of a folder archive: its pieces, or the error its stream throws. */
223
+ export interface TestFolderArchive {
224
+ chunks: readonly Buffer[];
225
+ summary?: Partial<AgentFolderArchiveSummary>;
226
+ }
227
+
228
+ /** What a test says of its devices' agents: a deployment's verdict, an inventory, folder archives. */
229
+ interface TestAgents {
230
+ dockerRun?: DevEyeFacade['agents']['dockerRun'];
231
+ dockerInventory?: DevEyeFacade['agents']['dockerInventory'];
232
+ /** By device id. A device without an entry answers nothing: its stream throws. */
233
+ archives?: Readonly<Record<string, TestFolderArchive | Error>>;
234
+ }
235
+
236
+ /** Replays the planned pieces; the summary appears once the last one is taken, as in the app. */
237
+ function replayedArchive(planned: TestFolderArchive | Error | undefined): AgentFolderArchive {
238
+ let summary: AgentFolderArchiveSummary | null = null;
239
+ return {
240
+ get summary() {
241
+ return summary;
242
+ },
243
+ async *[Symbol.asyncIterator]() {
244
+ if (!planned) throw new Error('No archive planned for this device');
245
+ if (planned instanceof Error) throw planned;
246
+ let bytesRead = 0;
247
+ for (const chunk of planned.chunks) {
248
+ bytesRead += chunk.length;
249
+ yield chunk;
250
+ }
251
+ summary = {
252
+ files: 1,
253
+ dirs: 0,
254
+ bytesRead,
255
+ skipped: 0,
256
+ changed: 0,
257
+ samples: [],
258
+ ...planned.summary
259
+ };
260
+ }
261
+ };
262
+ }
263
+
264
+ function recordingAgents(recorded: RecordedCalls, docker: TestAgents = {}): DevEyeFacade['agents'] {
198
265
  const req = (method: string) => (deviceId: string) => {
199
266
  recorded.agentRequests.push({ method, deviceId });
200
267
  return true;
@@ -226,7 +293,24 @@ function recordingAgents(recorded: RecordedCalls): DevEyeFacade['agents'] {
226
293
  // with a refusal injects its own facade through `deveye`.
227
294
  awaitFilesOp: () => Promise.resolve({ ok: true }),
228
295
  cancelFilesOp: () => undefined,
229
- buffered: () => 0
296
+ buffered: () => 0,
297
+ // Recorded, then answered as the test decides: success, and no
298
+ // inventory, by default.
299
+ dockerRun: (deviceId, order, options) => {
300
+ recorded.agentRequests.push({ method: 'dockerRun', deviceId });
301
+ return docker.dockerRun
302
+ ? docker.dockerRun(deviceId, order, options)
303
+ : Promise.resolve({ ok: true });
304
+ },
305
+ dockerInventory: (deviceId, timeoutMs) =>
306
+ docker.dockerInventory
307
+ ? docker.dockerInventory(deviceId, timeoutMs)
308
+ : Promise.resolve(null),
309
+ archiveFolder(deviceId, request) {
310
+ recorded.agentRequests.push({ method: 'archiveFolder', deviceId });
311
+ recorded.archiveRequests.push({ deviceId, ...request });
312
+ return replayedArchive(docker.archives?.[deviceId]);
313
+ }
230
314
  };
231
315
  }
232
316
 
@@ -243,6 +327,26 @@ function fakeDerive(salt: string, info: string, length: number): Uint8Array {
243
327
  return out;
244
328
  }
245
329
 
330
+ /** The plan pauses, from a fixed list by YOUR quota key: no key is checked against the manifest. */
331
+ function memoryPauses(
332
+ pausedItems: Readonly<Record<string, readonly string[]>> | undefined
333
+ ): SdkPlanPauses {
334
+ return {
335
+ isPaused: (key, itemId) => (pausedItems?.[key] ?? []).includes(itemId),
336
+ paused: (key) => pausedItems?.[key] ?? []
337
+ };
338
+ }
339
+
340
+ /** The app's refusal of a paused item run on demand. */
341
+ async function assertActiveIn(pauses: SdkPlanPauses, key: string, itemId: string): Promise<void> {
342
+ if (pauses.isPaused(key, itemId)) {
343
+ throw new FeatureError('quota_exceeded', `« ${key} » ${itemId} is paused by the plan`, {
344
+ key,
345
+ paused: true
346
+ });
347
+ }
348
+ }
349
+
246
350
  function memoryDomains(domains: readonly SdkDomain[]) {
247
351
  return {
248
352
  in: (workspaceId: number) => domains.filter((d) => d.workspaceId === workspaceId),
@@ -285,6 +389,8 @@ export interface TestContextOverrides<Repo> {
285
389
  quotaLimits?: Record<string, number>;
286
390
  /** The workspaces the owner account owns, handed to a quota counter. Default: the workspace of the call. */
287
391
  ownerWorkspaceIds?: readonly number[];
392
+ /** The items the plan holds paused, by YOUR `stock` quota key. Default none. */
393
+ pausedItems?: Record<string, readonly string[]>;
288
394
  canWrite?: boolean;
289
395
  /** Extra permissions the caller holds, as the grant would carry them. */
290
396
  extras?: Record<string, boolean | string>;
@@ -298,12 +404,23 @@ export interface TestContextOverrides<Repo> {
298
404
  hasRoute?: boolean;
299
405
  /** What `deveye.notify.send` resolves (no usable channel: false). Default true; recorded either way. */
300
406
  notifyAccepted?: boolean;
301
- /** What `ctx.origins` answers. Default `https://deveye.test` / `https://public.deveye.test`. */
302
- origins?: { app: string; public: string };
407
+ /** What `ctx.origins` answers. Default `https://deveye.test` / `https://public.deveye.test` / `https://site.deveye.test`. */
408
+ origins?: SdkOrigins;
303
409
  /** The channel ids `deveye.notify.liveChannels` lists. Default none. */
304
410
  liveChannels?: readonly number[];
305
411
  /** Devices `deveye.devices` reveals. Default none listed, any id authorized. */
306
412
  devices?: readonly SdkDevice[];
413
+ /**
414
+ * `deveye.devices.authorize` refuses any `extras`: the caller lacks them
415
+ * on every device (`true`) or on these ones. Default false.
416
+ */
417
+ refuseDeviceExtras?: boolean | readonly string[];
418
+ /** What `deveye.agents.dockerRun` resolves. Default success. */
419
+ dockerRun?: DevEyeFacade['agents']['dockerRun'];
420
+ /** What `deveye.agents.dockerInventory` resolves. Default null (no answer). */
421
+ dockerInventory?: DevEyeFacade['agents']['dockerInventory'];
422
+ /** What `deveye.agents.archiveFolder` streams, by device id. Default none: the stream throws. */
423
+ archives?: Readonly<Record<string, TestFolderArchive | Error>>;
307
424
  /** Instants `deveye.telemetry.snapshot` answers (matched within a second). Default none. */
308
425
  snapshots?: readonly SdkTelemetrySnapshot[];
309
426
  /** Override facade members entirely when the defaults are not enough. */
@@ -342,6 +459,7 @@ export function createTestContext<Repo = undefined>(
342
459
  liveMessages: [],
343
460
  audits: [],
344
461
  agentRequests: [],
462
+ archiveRequests: [],
345
463
  pinnedInstants: [],
346
464
  livePublishes: [],
347
465
  accountChanges: []
@@ -349,6 +467,7 @@ export function createTestContext<Repo = undefined>(
349
467
  const isOwner = overrides.isOwner ?? true;
350
468
  const workspaceId = overrides.workspaceId ?? 1;
351
469
  const canWrite = overrides.canWrite ?? true;
470
+ const pauses = memoryPauses(overrides.pausedItems);
352
471
  const deveye: DevEyeFacade = {
353
472
  notify: recordingNotify(
354
473
  recorded,
@@ -364,9 +483,9 @@ export function createTestContext<Repo = undefined>(
364
483
  ])
365
484
  },
366
485
  workspaces: { list: () => Promise.resolve(overrides.workspaces ?? []) },
367
- devices: recordingDevices(overrides.devices ?? []),
486
+ devices: recordingDevices(overrides.devices ?? [], overrides.refuseDeviceExtras ?? false),
368
487
  telemetry: recordingTelemetry(recorded, overrides.snapshots ?? []),
369
- agents: recordingAgents(recorded),
488
+ agents: recordingAgents(recorded, overrides),
370
489
  accounts: {
371
490
  me: () =>
372
491
  Promise.resolve(
@@ -418,6 +537,7 @@ export function createTestContext<Repo = undefined>(
418
537
  }
419
538
  },
420
539
  quota: {
540
+ ...pauses,
421
541
  limit: (key) => Promise.resolve(overrides.quotaLimits?.[key] ?? null),
422
542
  // The exact rule of the app: never counted when unlimited, refused
423
543
  // once the count AFTER creation passes the limit.
@@ -431,7 +551,8 @@ export function createTestContext<Repo = undefined>(
431
551
  limit
432
552
  });
433
553
  }
434
- }
554
+ },
555
+ assertActive: (key, itemId) => assertActiveIn(pauses, key, itemId)
435
556
  },
436
557
  items: {
437
558
  restrictions: () => Promise.resolve(restrictions),
@@ -517,7 +638,8 @@ export function createTestContext<Repo = undefined>(
517
638
  requestId: 'test',
518
639
  origins: overrides.origins ?? {
519
640
  app: 'https://deveye.test',
520
- public: 'https://public.deveye.test'
641
+ public: 'https://public.deveye.test',
642
+ site: 'https://site.deveye.test'
521
643
  }
522
644
  };
523
645
  }
@@ -543,18 +665,30 @@ export interface TestServiceOverrides<Repo> {
543
665
  workspaceIds?: readonly number[];
544
666
  /** Devices every workspace reveals. Default none. */
545
667
  devices?: readonly SdkDevice[];
668
+ /** What `membersFor(workspaceId).list()` answers, by workspace id. Default none. */
669
+ members?: Readonly<Record<number, Awaited<ReturnType<DevEyeFacade['members']['list']>>>>;
670
+ /** What `deps.agents.dockerRun` resolves. Default success. */
671
+ dockerRun?: DevEyeFacade['agents']['dockerRun'];
672
+ /** What `deps.agents.dockerInventory` resolves. Default null (no answer). */
673
+ dockerInventory?: DevEyeFacade['agents']['dockerInventory'];
674
+ /** What `deps.agents.archiveFolder` streams, by device id. Default none: the stream throws. */
675
+ archives?: Readonly<Record<string, TestFolderArchive | Error>>;
676
+ /** What `deps.access` answers. Default: every member holds every right. */
677
+ access?: Partial<FeatureServiceDeps['access']>;
546
678
  /** The accounts `deps.accounts` knows. Default none. */
547
679
  accounts?: readonly SdkAccount[];
548
680
  /** The plan's limits `deps.quotaFor` applies, by YOUR quota key. Default none (unlimited). */
549
681
  quotaLimits?: Record<string, number>;
682
+ /** The items the plan holds paused (`deps.pauses`), by YOUR `stock` quota key. Default none. */
683
+ pausedItems?: Record<string, readonly string[]>;
550
684
  /** What `deveyeFor(...).notify.hasRoute` answers. Default true. */
551
685
  hasRoute?: boolean;
552
686
  /** What `deveyeFor(...).notify.send` resolves. Default true; recorded either way. */
553
687
  notifyAccepted?: boolean;
554
688
  /** The channel ids `deveyeFor(...).notify.liveChannels` lists. Default none. */
555
689
  liveChannels?: readonly number[];
556
- /** What `deps.origins` answers. Default `https://deveye.test` / `https://public.deveye.test`. */
557
- origins?: { app: string; public: string };
690
+ /** What `deps.origins` answers. Default `https://deveye.test` / `https://public.deveye.test` / `https://site.deveye.test`. */
691
+ origins?: SdkOrigins;
558
692
  /** Instants `telemetry.snapshot` answers (matched within a second). Default none. */
559
693
  snapshots?: readonly SdkTelemetrySnapshot[];
560
694
  /** The feature's domains, every workspace mixed. Default none. */
@@ -576,6 +710,7 @@ export function createTestServiceDeps<Repo = undefined>(
576
710
  liveMessages: [],
577
711
  audits: [],
578
712
  agentRequests: [],
713
+ archiveRequests: [],
579
714
  pinnedInstants: [],
580
715
  livePublishes: [],
581
716
  accountChanges: [],
@@ -592,6 +727,7 @@ export function createTestServiceDeps<Repo = undefined>(
592
727
  overrides.liveChannels ?? []
593
728
  );
594
729
  const devices = recordingDevices(overrides.devices ?? []);
730
+ const pauses = memoryPauses(overrides.pausedItems);
595
731
  return {
596
732
  recorded,
597
733
  stores,
@@ -609,7 +745,8 @@ export function createTestServiceDeps<Repo = undefined>(
609
745
  deveyeFor: () => ({ notify }),
610
746
  origins: overrides.origins ?? {
611
747
  app: 'https://deveye.test',
612
- public: 'https://public.deveye.test'
748
+ public: 'https://public.deveye.test',
749
+ site: 'https://site.deveye.test'
613
750
  },
614
751
  secrecy: {
615
752
  redeem: (ticket) => {
@@ -632,6 +769,9 @@ export function createTestServiceDeps<Repo = undefined>(
632
769
  }
633
770
  },
634
771
  devicesFor: () => ({ list: devices.list, isOnline: devices.isOnline }),
772
+ membersFor: (workspaceId) => ({
773
+ list: () => Promise.resolve(overrides.members?.[workspaceId] ?? [])
774
+ }),
635
775
  devices: {
636
776
  find: (id) =>
637
777
  Promise.resolve((overrides.devices ?? []).find((d) => d.id === id) ?? null),
@@ -651,6 +791,7 @@ export function createTestServiceDeps<Repo = undefined>(
651
791
  }
652
792
  },
653
793
  quotaFor: () => ({
794
+ ...pauses,
654
795
  limit: (key) => Promise.resolve(overrides.quotaLimits?.[key] ?? null),
655
796
  async assert(key, countAfter) {
656
797
  const limit = overrides.quotaLimits?.[key];
@@ -661,8 +802,10 @@ export function createTestServiceDeps<Repo = undefined>(
661
802
  limit
662
803
  });
663
804
  }
664
- }
805
+ },
806
+ assertActive: (key, itemId) => assertActiveIn(pauses, key, itemId)
665
807
  }),
808
+ pauses,
666
809
  accounts: {
667
810
  find: (userId) =>
668
811
  Promise.resolve((overrides.accounts ?? []).find((a) => a.id === userId) ?? null),
@@ -698,7 +841,11 @@ export function createTestServiceDeps<Repo = undefined>(
698
841
  audit: (entry) => {
699
842
  recorded.audits.push({ action: entry.action, description: entry.description });
700
843
  },
701
- agents: recordingAgents(recorded),
844
+ agents: recordingAgents(recorded, overrides),
845
+ access: {
846
+ feature: overrides.access?.feature ?? (() => Promise.resolve({ ok: true })),
847
+ device: overrides.access?.device ?? (() => Promise.resolve({ ok: true }))
848
+ },
702
849
  // A fake wrapper: the sealed string is a handle to the bytes, and an
703
850
  // unknown handle opens to `null` exactly like a tampered blob would.
704
851
  keys: {
@@ -737,7 +884,14 @@ export function createTestServiceDeps<Repo = undefined>(
737
884
 
738
885
  /** A domain row for a test, verified by default. */
739
886
  export function testDomain(over: Partial<SdkDomain> & { id: number; host: string }): SdkDomain {
740
- return { workspaceId: 1, token: 'a'.repeat(32), verified: true, verifiedAt: 1, ...over };
887
+ return {
888
+ workspaceId: 1,
889
+ token: 'a'.repeat(32),
890
+ verified: true,
891
+ verifiedAt: 1,
892
+ planPaused: false,
893
+ ...over
894
+ };
741
895
  }
742
896
 
743
897
  /**
@@ -749,7 +903,7 @@ export function createTestDomainsContext<Repo = undefined>(
749
903
  overrides: {
750
904
  repo?: Repo;
751
905
  dns?: Partial<SdkDns>;
752
- origins?: { app: string; public: string };
906
+ origins?: SdkOrigins;
753
907
  } = {}
754
908
  ): FeatureDomainsContext<Repo> {
755
909
  const stores = new Map<number, TestFeatureStore>();
@@ -758,7 +912,8 @@ export function createTestDomainsContext<Repo = undefined>(
758
912
  repo: overrides.repo as Repo,
759
913
  origins: overrides.origins ?? {
760
914
  app: 'https://deveye.test',
761
- public: 'https://public.deveye.test'
915
+ public: 'https://public.deveye.test',
916
+ site: 'https://site.deveye.test'
762
917
  },
763
918
  cipherFor: () => identityCipher,
764
919
  storeFor(workspaceId) {