@c9up/archive 0.1.20 → 0.1.21

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.
Files changed (87) hide show
  1. package/README.md +96 -3
  2. package/dist/ArchiveProvider.d.ts +6 -1
  3. package/dist/ArchiveProvider.d.ts.map +1 -1
  4. package/dist/ArchiveProvider.js +73 -1
  5. package/dist/ArchiveProvider.js.map +1 -1
  6. package/dist/DriveManager.d.ts +10 -3
  7. package/dist/DriveManager.d.ts.map +1 -1
  8. package/dist/DriveManager.js +23 -6
  9. package/dist/DriveManager.js.map +1 -1
  10. package/dist/GcsDriver.d.ts +14 -9
  11. package/dist/GcsDriver.d.ts.map +1 -1
  12. package/dist/GcsDriver.js +202 -98
  13. package/dist/GcsDriver.js.map +1 -1
  14. package/dist/S3Driver.d.ts +11 -7
  15. package/dist/S3Driver.d.ts.map +1 -1
  16. package/dist/S3Driver.js +73 -110
  17. package/dist/S3Driver.js.map +1 -1
  18. package/dist/StaticMiddleware.d.ts +5 -1
  19. package/dist/StaticMiddleware.d.ts.map +1 -1
  20. package/dist/StaticMiddleware.js +114 -13
  21. package/dist/StaticMiddleware.js.map +1 -1
  22. package/dist/StorageManager.d.ts +28 -3
  23. package/dist/StorageManager.d.ts.map +1 -1
  24. package/dist/StorageManager.js +333 -132
  25. package/dist/StorageManager.js.map +1 -1
  26. package/dist/augmentations.d.ts +17 -0
  27. package/dist/augmentations.d.ts.map +1 -1
  28. package/dist/errno.d.ts +6 -0
  29. package/dist/errno.d.ts.map +1 -0
  30. package/dist/errno.js +11 -0
  31. package/dist/errno.js.map +1 -0
  32. package/dist/index.d.ts +1 -0
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js.map +1 -1
  35. package/dist/keys.d.ts +34 -0
  36. package/dist/keys.d.ts.map +1 -0
  37. package/dist/keys.js +88 -0
  38. package/dist/keys.js.map +1 -0
  39. package/dist/local-signature.d.ts +32 -0
  40. package/dist/local-signature.d.ts.map +1 -0
  41. package/dist/local-signature.js +58 -0
  42. package/dist/local-signature.js.map +1 -0
  43. package/dist/move-to-disk.d.ts +24 -0
  44. package/dist/move-to-disk.d.ts.map +1 -0
  45. package/dist/move-to-disk.js +167 -0
  46. package/dist/move-to-disk.js.map +1 -0
  47. package/dist/objects.d.ts.map +1 -1
  48. package/dist/objects.js +5 -2
  49. package/dist/objects.js.map +1 -1
  50. package/dist/provider-fetch.d.ts +36 -0
  51. package/dist/provider-fetch.d.ts.map +1 -0
  52. package/dist/provider-fetch.js +158 -0
  53. package/dist/provider-fetch.js.map +1 -0
  54. package/dist/services/main.d.ts +1 -1
  55. package/dist/services/main.d.ts.map +1 -1
  56. package/dist/services/main.js +14 -1
  57. package/dist/services/main.js.map +1 -1
  58. package/dist/signed-route.d.ts +18 -6
  59. package/dist/signed-route.d.ts.map +1 -1
  60. package/dist/signed-route.js +186 -31
  61. package/dist/signed-route.js.map +1 -1
  62. package/dist/streams.d.ts +36 -0
  63. package/dist/streams.d.ts.map +1 -0
  64. package/dist/streams.js +108 -0
  65. package/dist/streams.js.map +1 -0
  66. package/dist/testing/FakeStorage.d.ts.map +1 -1
  67. package/dist/testing/FakeStorage.js +2 -1
  68. package/dist/testing/FakeStorage.js.map +1 -1
  69. package/package.json +7 -3
  70. package/src/ArchiveProvider.ts +105 -4
  71. package/src/DriveManager.ts +32 -6
  72. package/src/GcsDriver.ts +256 -139
  73. package/src/S3Driver.ts +87 -130
  74. package/src/StaticMiddleware.ts +124 -13
  75. package/src/StorageManager.ts +398 -141
  76. package/src/augmentations.ts +24 -1
  77. package/src/errno.ts +10 -0
  78. package/src/index.ts +1 -0
  79. package/src/keys.ts +104 -0
  80. package/src/local-signature.ts +76 -0
  81. package/src/move-to-disk.ts +234 -0
  82. package/src/objects.ts +5 -2
  83. package/src/provider-fetch.ts +171 -0
  84. package/src/services/main.ts +15 -2
  85. package/src/signed-route.ts +216 -36
  86. package/src/streams.ts +118 -0
  87. package/src/testing/FakeStorage.ts +2 -3
@@ -5,7 +5,9 @@
5
5
  * `archive` config key.
6
6
  *
7
7
  * Duck-typed against `ArchiveAppContext` so archive does NOT import
8
- * `@c9up/ream` — keeps the package publishable standalone.
8
+ * `@c9up/ream` statically — keeps the package publishable standalone. At
9
+ * boot it gives ream's uploads `moveToDisk(key, disk?, options?)` when ream
10
+ * is installed (see `move-to-disk.ts`).
9
11
  *
10
12
  * @example
11
13
  * // reamrc.ts
@@ -26,10 +28,12 @@ import { type DriveConfig, DriveManager } from "./DriveManager.js";
26
28
  import { ArchiveError } from "./errors.js";
27
29
 
28
30
  import { type GcsConfig, GcsDriver } from "./GcsDriver.js";
31
+ import { extendMultipartFile } from "./move-to-disk.js";
29
32
  import { type S3Config, S3Driver } from "./S3Driver.js";
30
33
  import {
31
34
  LocalDriver,
32
35
  type ReleasableSecret,
36
+ type SignedUrlOptions,
33
37
  type StorageDriver,
34
38
  StorageManager,
35
39
  } from "./StorageManager.js";
@@ -50,6 +54,8 @@ interface ArchiveConfigStore {
50
54
  export interface ArchiveAppContext {
51
55
  container: ArchiveContainer;
52
56
  config: ArchiveConfigStore;
57
+ /** Set by inker's provider when the app renders views with it. */
58
+ usingInker?: boolean;
53
59
  }
54
60
 
55
61
  /**
@@ -60,7 +66,11 @@ export interface ArchiveAppContext {
60
66
  */
61
67
  export interface ArchiveConfig {
62
68
  driver: "local" | "s3" | "gcs";
63
- local?: { root: string; signingSecret?: string | ReleasableSecret };
69
+ local?: {
70
+ root: string;
71
+ signingSecret?: string | ReleasableSecret;
72
+ routeBasePath?: string;
73
+ };
64
74
  s3?: S3Config;
65
75
  gcs?: GcsConfig;
66
76
  }
@@ -80,6 +90,9 @@ export default class ArchiveProvider {
80
90
  */
81
91
  #storage: (() => StorageManager) | undefined;
82
92
 
93
+ /** The lazily-built disk manager behind it, likewise set by register(). */
94
+ #drive: (() => DriveManager) | undefined;
95
+
83
96
  constructor(protected app: ArchiveAppContext) {}
84
97
 
85
98
  register(): void {
@@ -109,6 +122,7 @@ export default class ArchiveProvider {
109
122
  return manager;
110
123
  };
111
124
  this.#storage = storageManager;
125
+ this.#drive = driveManager;
112
126
 
113
127
  this.app.container.singleton(DriveManager, () => driveManager());
114
128
  // Backward-compatible bindings — the default disk is what apps
@@ -139,6 +153,11 @@ export default class ArchiveProvider {
139
153
  // The accessor reads the same cell the container's bindings read, so
140
154
  // however storage is reached there is one manager behind it.
141
155
  setStorageResolver(storage);
156
+ await this.#registerViewHelpers();
157
+ // Lazy like the helpers: the macro resolves the disk when an upload is
158
+ // moved, so an unconfigured app builds nothing here.
159
+ const drive = this.#drive;
160
+ if (drive !== undefined) await extendMultipartFile(drive);
142
161
 
143
162
  // No eager construction when archive is unconfigured: an app that
144
163
  // registers this provider and never uses storage should not trigger
@@ -161,6 +180,63 @@ export default class ArchiveProvider {
161
180
  setStorage(manager);
162
181
  }
163
182
 
183
+ /**
184
+ * Publish `driveUrl` and `driveSignedUrl` to templates, as upstream's
185
+ * provider does for its view engine:
186
+ *
187
+ * {{ await driveUrl(user.avatar) }}
188
+ * {{ await driveSignedUrl(invoice.pdf, 'invoices', { expiresIn: '1h' }) }}
189
+ *
190
+ * Only when the app renders with inker (its provider sets `usingInker`),
191
+ * through inker's module singleton — the same way the i18n package
192
+ * publishes its globals, for the same reason: the engine's container
193
+ * binding is not resolvable during boot, while the singleton's `use()`
194
+ * queues the plugin until the first render. Nothing is built here: each
195
+ * helper resolves the disk when a template calls it.
196
+ */
197
+ async #registerViewHelpers(): Promise<void> {
198
+ const drive = this.#drive;
199
+ if (this.app.usingInker !== true || drive === undefined) return;
200
+ // Computed: inker is an optional peer, so a bundler must not try to
201
+ // resolve it for an application that does not install it.
202
+ const specifier = "@c9up/inker";
203
+ const loaded: unknown = await import(/* @vite-ignore */ specifier);
204
+ const engine =
205
+ typeof loaded === "object" && loaded !== null
206
+ ? Reflect.get(loaded, "default")
207
+ : undefined;
208
+ const plugin = (target: unknown): void => {
209
+ if (!publishesGlobals(target)) return;
210
+ target.global("driveUrl", (key: string, disk?: string) =>
211
+ drive().use(disk).getUrl(key),
212
+ );
213
+ target.global(
214
+ "driveSignedUrl",
215
+ (
216
+ key: string,
217
+ diskOrOptions?: string | SignedUrlOptions,
218
+ options?: SignedUrlOptions,
219
+ ) =>
220
+ typeof diskOrOptions === "string"
221
+ ? drive().use(diskOrOptions).getSignedUrl(key, options)
222
+ : drive()
223
+ .use()
224
+ .getSignedUrl(key, diskOrOptions ?? options),
225
+ );
226
+ };
227
+ if (isPluggable(engine)) engine.use(plugin);
228
+ else if (publishesGlobals(engine)) plugin(engine);
229
+ else {
230
+ throw new ArchiveError(
231
+ "E_ARCHIVE_TEMPLATE_ENGINE",
232
+ "The app renders with inker, but its module exposes neither use() nor global(): the drive template helpers cannot be published.",
233
+ {
234
+ hint: "Install a @c9up/inker version whose default export has use(plugin) or global(name, value).",
235
+ },
236
+ );
237
+ }
238
+ }
239
+
164
240
  async start(): Promise<void> {}
165
241
  async ready(): Promise<void> {}
166
242
  async shutdown(): Promise<void> {
@@ -174,14 +250,38 @@ export default class ArchiveProvider {
174
250
  }
175
251
  }
176
252
 
253
+ /** An engine that queues plugins until it renders: inker's module singleton. */
254
+ function isPluggable(
255
+ value: unknown,
256
+ ): value is { use(plugin: (target: unknown) => void): unknown } {
257
+ return (
258
+ typeof value === "object" &&
259
+ value !== null &&
260
+ "use" in value &&
261
+ typeof value.use === "function"
262
+ );
263
+ }
264
+
265
+ /** An engine that publishes template globals. */
266
+ function publishesGlobals(
267
+ value: unknown,
268
+ ): value is { global(name: string, value: unknown): unknown } {
269
+ return (
270
+ typeof value === "object" &&
271
+ value !== null &&
272
+ "global" in value &&
273
+ typeof value.global === "function"
274
+ );
275
+ }
276
+
177
277
  /** Narrow an unknown config value to the multi-disk {@link DriveConfig} shape. */
178
278
  function isDriveConfig(config: unknown): config is DriveConfig {
179
279
  return (
180
280
  typeof config === "object" &&
181
281
  config !== null &&
182
282
  "services" in config &&
183
- typeof (config as { services: unknown }).services === "object" &&
184
- (config as { services: unknown }).services !== null
283
+ typeof config.services === "object" &&
284
+ config.services !== null
185
285
  );
186
286
  }
187
287
 
@@ -231,6 +331,7 @@ function buildDriver(config: ArchiveConfig): StorageDriver {
231
331
  const root = config.local?.root ?? "./storage";
232
332
  return new LocalDriver(root, {
233
333
  signingSecret: config.local?.signingSecret,
334
+ routeBasePath: config.local?.routeBasePath,
234
335
  });
235
336
  }
236
337
  // Reject unknown driver values explicitly so a typo like
@@ -58,15 +58,22 @@ export interface FsServiceOptions {
58
58
  * `Secret`, kept wrapped here and released by the driver.
59
59
  */
60
60
  signingSecret?: string | ReleasableSecret;
61
+ /**
62
+ * URL path the disk's files are served under (default `/storage`): the
63
+ * driver's URLs and the signed route both derive from it.
64
+ */
65
+ routeBasePath?: string;
61
66
  }
62
67
 
63
68
  /**
64
69
  * Config helpers mirroring AdonisJS Drive's `services.fs/s3/gcs`. Each
65
70
  * returns a factory consumed by {@link DriveConfig.services}.
66
71
  *
67
- * DIVERGENCE (documented, deliberate): the ream `services.fs` builds URLs
68
- * in-package via the LocalDriver + signed-route handler — it does NOT
69
- * couple to the ream router the way Adonis wires `serveFiles`/`routeBasePath`.
72
+ * NAMED DEVIATION: the ream `services.fs` builds URLs in-package via the
73
+ * LocalDriver + signed-route handler — it does NOT couple to the router,
74
+ * so there is no `serveFiles` that registers the route for you. Its
75
+ * `routeBasePath` plays the upstream role all the same: the driver's URLs
76
+ * and the signed route's prefix both derive from it.
70
77
  */
71
78
  export const services: {
72
79
  fs(options?: FsServiceOptions): DriveServiceFactory;
@@ -76,7 +83,10 @@ export const services: {
76
83
  fs(options) {
77
84
  const root = options?.location ?? options?.root ?? "./storage";
78
85
  return () =>
79
- new LocalDriver(root, { signingSecret: options?.signingSecret });
86
+ new LocalDriver(root, {
87
+ signingSecret: options?.signingSecret,
88
+ routeBasePath: options?.routeBasePath,
89
+ });
80
90
  },
81
91
  s3(config) {
82
92
  return () => new S3Driver(config);
@@ -86,13 +96,29 @@ export const services: {
86
96
  },
87
97
  };
88
98
 
99
+ /**
100
+ * The factory configured for a disk, or `undefined` when there is none. Only
101
+ * OWN entries of `services` are disks: a plain lookup would answer
102
+ * `constructor`, `toString` or `hasOwnProperty` with the function inherited
103
+ * from `Object.prototype` and build a broken disk out of it.
104
+ *
105
+ * NAMED DEVIATION (stricter than flydrive's `DriveManager.use`, which reads
106
+ * `services[name]` directly): an inherited name is an unknown disk.
107
+ */
108
+ function serviceFactory(
109
+ services: Record<string, DriveServiceFactory>,
110
+ name: string,
111
+ ): DriveServiceFactory | undefined {
112
+ return Object.hasOwn(services, name) ? services[name] : undefined;
113
+ }
114
+
89
115
  export class DriveManager {
90
116
  #config: DriveConfig;
91
117
  #cache = new Map<string, StorageManager>();
92
118
  #fakes = new Map<string, FakeStorageManager>();
93
119
 
94
120
  constructor(config: DriveConfig) {
95
- if (config.services[config.default] === undefined) {
121
+ if (serviceFactory(config.services, config.default) === undefined) {
96
122
  throw new ArchiveError(
97
123
  "E_ARCHIVE_UNKNOWN_DISK",
98
124
  `Archive default disk '${config.default}' is not present in config.services`,
@@ -115,7 +141,7 @@ export class DriveManager {
115
141
  if (fake) return fake;
116
142
  const cached = this.#cache.get(name);
117
143
  if (cached) return cached;
118
- const factory = this.#config.services[name];
144
+ const factory = serviceFactory(this.#config.services, name);
119
145
  if (factory === undefined) {
120
146
  throw new ArchiveError(
121
147
  "E_ARCHIVE_UNKNOWN_DISK",