@milaboratories/pl-model-middle-layer 1.8.10 → 1.8.12

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 (4) hide show
  1. package/dist/pframe/internal_api/http_helpers.d.ts +76 -90
  2. package/dist/pframe/internal_api/http_helpers.d.ts.map +1 -1
  3. package/package.json +6 -6
  4. package/src/pframe/internal_api/http_helpers.ts +81 -94
package/dist/pframe/internal_api/http_helpers.d.ts CHANGED
@@ -1,14 +1,6 @@
1
1
  import type { Readable } from 'node:stream';
2
2
  import type { RequestListener } from 'node:http';
3
- import type { AddressInfo } from 'node:net';
4
- import type { Branded } from '@milaboratories/pl-model-common';
5
- /** File statistics */
6
- export type FileStats = {
7
- /** File size in bytes */
8
- size: number;
9
- /** File modification time if available */
10
- mtime?: Date;
11
- };
3
+ import type { Branded, Base64Encoded } from '@milaboratories/pl-model-common';
12
4
  /** File range specification */
13
5
  export type FileRange = {
14
6
  /** Start byte position (inclusive) */
@@ -24,151 +16,145 @@ export type FileRange = {
24
16
  */
25
17
  export interface ObjectStore {
26
18
  /**
27
- * Check if file exists
19
+ * @returns file size in bytes or `-1` if file does not exist or permissions do not allow access.
20
+ * @throws if file can become accessible after retry (e.g. on network error)
28
21
  *
29
22
  * @example
30
23
  * ```ts
31
- * async fileExists(filename: string): Promise<boolean> {
24
+ * async getFileSize(filename: string): Promise<number> {
32
25
  * const filePath = this.resolve(filename);
33
- * try {
34
- * await fs.access(filePath, constants.F_OK);
35
- * return true;
36
- * } catch {
37
- * return false;
38
- * }
26
+ * return await fs
27
+ * .stat(filePath)
28
+ * .then((stat) => ({ size: stat.isFile() ? stat.size : -1 }))
29
+ * .catch(() => ({ size: -1 }));
39
30
  * }
40
31
  * ```
41
32
  */
42
- fileExists(filename: string): Promise<boolean>;
33
+ getFileSize(filename: string): Promise<number>;
43
34
  /**
44
- * Get file statistics
35
+ * Execute action with readable stream (actions can be concurrency limited by the store).
36
+ * Action resolves when stream is closed by handler @see HttpHelpers.createRequestHandler
45
37
  *
46
- * @example
47
- * ```ts
48
- * async getFileStats(filename: string): Promise<FileStats> {
49
- * const filePath = this.resolve(filename);
50
- * try {
51
- * const stats = await fs.stat(filePath);
52
- * return {
53
- * size: stats.size,
54
- * mtime: stats.mtime
55
- * };
56
- * } catch (err: unknown) {
57
- * throw new Error(
58
- * `Failed to get file statistics for: ${filename} - ${ensureError(err)}`
59
- * );
60
- * }
61
- * }
62
- * ```
63
- */
64
- getFileStats(filename: string): Promise<FileStats>;
65
- /**
66
- * Execute action with readable stream.
67
- * Action resolves when stream is closed eigher by handler
68
- * @see HttpHelpers.createRequestHandler or the store itself.
69
- * Returned promise resolves after the action is completed.
38
+ * @param filename - existing file name (for which @see ObjectStore.getFileSize returned non-negative value)
39
+ * @param range - valid range of bytes to read from the file (store may skip validation)
40
+ * @param action - function to execute with the stream, responsible for closing the stream
41
+ * @returns promise that resolves after the action is completed
70
42
  *
71
43
  * @example
72
44
  * ```ts
73
45
  * async withReadStream(params: {
74
46
  * filename: string;
75
- * range?: FileRange;
47
+ * range: FileRange;
76
48
  * action: (stream: Readable) => Promise<void>;
77
49
  * }): Promise<void> {
78
50
  * const { filename, range, action } = params;
79
51
  * const filePath = this.resolve(filename);
80
52
  *
81
- * let stream: Readable;
82
53
  * try {
83
- * stream = createReadStream(filePath, range);
54
+ * const stream = createReadStream(filePath, range);
55
+ * return await action(stream);
84
56
  * } catch (err: unknown) {
85
- * throw new Error(
86
- * `Failed to create read stream for: ${filename} - ${ensureError(err)}`
87
- * );
88
- * }
89
- *
90
- * try {
91
- * await action(stream);
92
- * } finally {
93
- * if (!stream.destroyed) {
94
- * stream.destroy();
95
- * }
57
+ * console.error(`failed to create read stream for ${filename} - ${ensureError(err)}`);
58
+ * throw;
96
59
  * }
97
60
  * }
98
61
  * ```
99
62
  */
100
63
  withReadStream(params: {
101
64
  filename: string;
65
+ range: FileRange;
102
66
  action: (stream: Readable) => Promise<void>;
103
- range?: FileRange;
104
67
  }): Promise<void>;
105
68
  }
106
69
  /** Object store base URL in format accepted by Apache DataFusion and DuckDB */
107
70
  export type ObjectStoreUrl = Branded<string, 'PFrameInternal.ObjectStoreUrl'>;
71
+ /** HTTP(S) request handler creation options */
72
+ export type RequestHandlerOptions = {
73
+ /** Object store to serve files from, @see HttpHelpers.createFsStore */
74
+ store: ObjectStore;
75
+ };
108
76
  /** Server configuration options */
109
77
  export type HttpServerOptions = {
110
- /** HTTP request handler function */
78
+ /** HTTP(S) request handler function, @see HttpHelpers.createRequestHandler */
111
79
  handler: RequestListener;
112
- /** Host to bind to (defaults to '127.0.0.1') */
113
- host?: string;
114
- /** Port to bind to (defaults to 0 for auto-assignment) */
80
+ /** Port to bind to (@default 0 for auto-assignment) */
115
81
  port?: number;
116
- /** AbortSignal to stop the server */
117
- signal: AbortSignal;
82
+ /** Do not apply authorization middleware to @param handler */
83
+ noAuth?: true;
84
+ /** Downgrade default HTTPS server to plain HTTP, @warning use only for testing */
85
+ http?: true;
118
86
  };
119
- /** Result of the server start operation */
120
- export type HttpServerStartResult = {
121
- /** Server address info */
122
- address: AddressInfo;
87
+ /**
88
+ * Long unique opaque string for use in Bearer authorization header
89
+ *
90
+ * @example
91
+ * ```ts
92
+ * request.setHeader('Authorization', `Bearer ${authToken}`);
93
+ * ```
94
+ */
95
+ export type HttpAuthorizationToken = Branded<string, 'PFrameInternal.HttpAuthorizationToken'>;
96
+ /**
97
+ * TLS certificate in PEM format
98
+ *
99
+ * @example
100
+ * ```txt
101
+ * -----BEGIN CERTIFICATE-----
102
+ * MIIC2zCCAcOgAwIBAgIJaVW7...
103
+ * ...
104
+ * ...Yf9CRK8fgnukKM7TJ
105
+ * -----END CERTIFICATE-----
106
+ * ```
107
+ */
108
+ export type PemCertificate = Branded<string, 'PFrameInternal.PemCertificate'>;
109
+ /** HTTP(S) server information and controls, @see HttpHelpers.createHttpServer */
110
+ export interface HttpServer {
111
+ /** Server address info formatted as `http{s}://<host>:<port>/` */
112
+ get address(): ObjectStoreUrl;
113
+ /** Authorization token for Bearer scheme, undefined when @see HttpServerOptions.noAuth flag is set */
114
+ get authToken(): HttpAuthorizationToken | undefined;
115
+ /** Base64-encoded CA certificate in PEM format, undefined when @see HttpServerOptions.http flag is set */
116
+ get encodedCaCert(): Base64Encoded<PemCertificate> | undefined;
123
117
  /** Promise that resolves when the server is stopped */
124
- stopped: Promise<void>;
125
- };
118
+ get stopped(): Promise<void>;
119
+ /** Request server stop, returns the same promise as @see HttpServer.stopped */
120
+ stop(): Promise<void>;
121
+ }
122
+ /** List of HTTP(S) related helper functions exposed by PFrame module */
126
123
  export interface HttpHelpers {
127
124
  /**
128
125
  * Create an object store for serving files from a local directory.
129
126
  * Rejects if the provided path does not exist or is not a directory.
130
- * Intended for testing purposes, you will probably want to implement a different store.
131
127
  */
132
128
  createFsStore(rootDir: string): Promise<ObjectStore>;
133
129
  /**
134
130
  * Create an HTTP request handler for serving files from an object store.
135
- * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise.
131
+ * Accepts only paths of the form `/<filename>.parquet`, returns 410 otherwise.
136
132
  * Assumes that files are immutable (and sets cache headers accordingly).
137
133
  */
138
- createRequestHandler(store: ObjectStore): RequestListener;
139
- /**
140
- * Create an object store URL from the server address info.
141
- * Result of this function is intended to be passed to PFrames as data source parquet prefix.
142
- */
143
- createObjectStoreUrl(info: AddressInfo): ObjectStoreUrl;
134
+ createRequestHandler(options: RequestHandlerOptions): RequestListener;
144
135
  /**
145
- * Serve HTTP requests using the provided handler on the given host and port.
146
- * Returns a promise that resolves when the server is stopped.
136
+ * Serve HTTP(S) requests using the provided handler on localhost port.
137
+ * @returns promise that resolves when the server has stopped.
147
138
  *
148
139
  * @example
149
140
  * ```ts
150
- * const abortController = new AbortController();
151
141
  * const rootDir = '/path/to/directory/with/parquet/files';
152
- * const port = 3000;
153
142
  *
154
143
  * let store = await HttpHelpers.createFsStore(rootDir).catch((err: unknown) => {
155
144
  * throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);
156
145
  * });
157
146
  *
158
- * const { address: serverAddress, stopped: serverStopped } = await HttpHelpers.serve({
147
+ * const server = await HttpHelpers.createHttpServer({
159
148
  * handler: HttpHelpers.createRequestHandler(store),
160
- * port,
161
- * signal: abortController.signal
162
149
  * }).catch((err: unknown) => {
163
- * throw new Error(`Failed to start http server on port ${port} - ${ensureError(err)}`);
150
+ * throw new Error(`Failed to start HTTP server - ${ensureError(err)}`);
164
151
  * });
165
152
  *
166
- * const _ = HttpHelpers.createObjectStoreUrl(serverAddress);
153
+ * const { address, authToken, base64EncodedCaCert } = server;
167
154
  *
168
- * abortController.abort();
169
- * await serverStopped;
155
+ * await server.stop();
170
156
  * ```
171
157
  */
172
- serve(options: HttpServerOptions): Promise<HttpServerStartResult>;
158
+ createHttpServer(options: HttpServerOptions): Promise<HttpServer>;
173
159
  }
174
160
  //# sourceMappingURL=http_helpers.d.ts.map
package/dist/pframe/internal_api/http_helpers.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"http_helpers.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/http_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAE/D,sBAAsB;AACtB,MAAM,MAAM,SAAS,GAAG;IACtB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,CAAC,EAAE,IAAI,CAAC;CACd,CAAC;AAEF,+BAA+B;AAC/B,MAAM,MAAM,SAAS,GAAG;IACtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,cAAc,CAAC,MAAM,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5C,KAAK,CAAC,EAAE,SAAS,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;AAE9E,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,oCAAoC;IACpC,OAAO,EAAE,eAAe,CAAC;IACzB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,qBAAqB,GAAG;IAClC,0BAA0B;IAC1B,OAAO,EAAE,WAAW,CAAC;IACrB,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAErD;;;;OAIG;IACH,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,CAAC;IAE1D;;;OAGG;IACH,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,cAAc,CAAC;IAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACnE"}
1
+ {"version":3,"file":"http_helpers.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/http_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAE9E,+BAA+B;AAC/B,MAAM,MAAM,SAAS,GAAG;IACtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cAAc,CAAC,MAAM,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,SAAS,CAAC;QACjB,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC7C,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;AAE9E,+CAA+C;AAC/C,MAAM,MAAM,qBAAqB,GAAG;IAClC,uEAAuE;IACvE,KAAK,EAAE,WAAW,CAAC;CAEpB,CAAA;AAED,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,eAAe,CAAC;IACzB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,kFAAkF;IAClF,IAAI,CAAC,EAAE,IAAI,CAAC;CACb,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,uCAAuC,CAAC,CAAC;AAE9F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;AAE9E,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,IAAI,OAAO,IAAI,cAAc,CAAC;IAC9B,sGAAsG;IACtG,IAAI,SAAS,IAAI,sBAAsB,GAAG,SAAS,CAAC;IACpD,0GAA0G;IAC1G,IAAI,aAAa,IAAI,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAC/D,uDAAuD;IACvD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,+EAA+E;IAC/E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAErD;;;;OAIG;IACH,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CAAC;IAEtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnE"}
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@milaboratories/pl-model-middle-layer",
3
- "version": "1.8.10",
3
+ "version": "1.8.12",
4
4
  "description": "Common model between middle layer and non-block UI code",
5
+ "type": "module",
5
6
  "types": "./dist/index.d.ts",
6
- "main": "./dist/index.cjs",
7
- "module": "./dist/index.js",
7
+ "main": "./dist/index.js",
8
8
  "exports": {
9
9
  ".": {
10
10
  "types": "./dist/index.d.ts",
@@ -20,13 +20,13 @@
20
20
  "remeda": "^2.28.0",
21
21
  "zod": "~3.23.8",
22
22
  "utility-types": "^3.11.0",
23
- "@milaboratories/pl-model-common": "^1.19.11"
23
+ "@milaboratories/pl-model-common": "^1.19.13"
24
24
  },
25
25
  "devDependencies": {
26
26
  "typescript": "~5.6.3",
27
- "@milaboratories/build-configs": "1.0.8",
27
+ "@milaboratories/ts-builder": "1.0.5",
28
28
  "@milaboratories/ts-configs": "1.0.6",
29
- "@milaboratories/ts-builder": "1.0.4"
29
+ "@milaboratories/build-configs": "1.0.8"
30
30
  },
31
31
  "scripts": {
32
32
  "type-check": "ts-builder types --target node",
package/src/pframe/internal_api/http_helpers.ts CHANGED
@@ -1,15 +1,6 @@
1
1
  import type { Readable } from 'node:stream';
2
2
  import type { RequestListener } from 'node:http';
3
- import type { AddressInfo } from 'node:net';
4
- import type { Branded } from '@milaboratories/pl-model-common';
5
-
6
- /** File statistics */
7
- export type FileStats = {
8
- /** File size in bytes */
9
- size: number;
10
- /** File modification time if available */
11
- mtime?: Date;
12
- };
3
+ import type { Branded, Base64Encoded } from '@milaboratories/pl-model-common';
13
4
 
14
5
  /** File range specification */
15
6
  export type FileRange = {
@@ -27,159 +18,155 @@ export type FileRange = {
27
18
  */
28
19
  export interface ObjectStore {
29
20
  /**
30
- * Check if file exists
31
- *
32
- * @example
33
- * ```ts
34
- * async fileExists(filename: string): Promise<boolean> {
35
- * const filePath = this.resolve(filename);
36
- * try {
37
- * await fs.access(filePath, constants.F_OK);
38
- * return true;
39
- * } catch {
40
- * return false;
41
- * }
42
- * }
43
- * ```
44
- */
45
- fileExists(filename: string): Promise<boolean>;
46
-
47
- /**
48
- * Get file statistics
21
+ * @returns file size in bytes or `-1` if file does not exist or permissions do not allow access.
22
+ * @throws if file can become accessible after retry (e.g. on network error)
49
23
  *
50
24
  * @example
51
25
  * ```ts
52
- * async getFileStats(filename: string): Promise<FileStats> {
26
+ * async getFileSize(filename: string): Promise<number> {
53
27
  * const filePath = this.resolve(filename);
54
- * try {
55
- * const stats = await fs.stat(filePath);
56
- * return {
57
- * size: stats.size,
58
- * mtime: stats.mtime
59
- * };
60
- * } catch (err: unknown) {
61
- * throw new Error(
62
- * `Failed to get file statistics for: ${filename} - ${ensureError(err)}`
63
- * );
64
- * }
28
+ * return await fs
29
+ * .stat(filePath)
30
+ * .then((stat) => ({ size: stat.isFile() ? stat.size : -1 }))
31
+ * .catch(() => ({ size: -1 }));
65
32
  * }
66
33
  * ```
67
34
  */
68
- getFileStats(filename: string): Promise<FileStats>;
35
+ getFileSize(filename: string): Promise<number>;
69
36
 
70
37
  /**
71
- * Execute action with readable stream.
72
- * Action resolves when stream is closed eigher by handler
73
- * @see HttpHelpers.createRequestHandler or the store itself.
74
- * Returned promise resolves after the action is completed.
38
+ * Execute action with readable stream (actions can be concurrency limited by the store).
39
+ * Action resolves when stream is closed by handler @see HttpHelpers.createRequestHandler
40
+ *
41
+ * @param filename - existing file name (for which @see ObjectStore.getFileSize returned non-negative value)
42
+ * @param range - valid range of bytes to read from the file (store may skip validation)
43
+ * @param action - function to execute with the stream, responsible for closing the stream
44
+ * @returns promise that resolves after the action is completed
75
45
  *
76
46
  * @example
77
47
  * ```ts
78
48
  * async withReadStream(params: {
79
49
  * filename: string;
80
- * range?: FileRange;
50
+ * range: FileRange;
81
51
  * action: (stream: Readable) => Promise<void>;
82
52
  * }): Promise<void> {
83
53
  * const { filename, range, action } = params;
84
54
  * const filePath = this.resolve(filename);
85
55
  *
86
- * let stream: Readable;
87
56
  * try {
88
- * stream = createReadStream(filePath, range);
57
+ * const stream = createReadStream(filePath, range);
58
+ * return await action(stream);
89
59
  * } catch (err: unknown) {
90
- * throw new Error(
91
- * `Failed to create read stream for: ${filename} - ${ensureError(err)}`
92
- * );
93
- * }
94
- *
95
- * try {
96
- * await action(stream);
97
- * } finally {
98
- * if (!stream.destroyed) {
99
- * stream.destroy();
100
- * }
60
+ * console.error(`failed to create read stream for ${filename} - ${ensureError(err)}`);
61
+ * throw;
101
62
  * }
102
63
  * }
103
64
  * ```
104
65
  */
105
66
  withReadStream(params: {
106
67
  filename: string;
68
+ range: FileRange;
107
69
  action: (stream: Readable) => Promise<void>;
108
- range?: FileRange;
109
70
  }): Promise<void>;
110
71
  }
111
72
 
112
73
  /** Object store base URL in format accepted by Apache DataFusion and DuckDB */
113
74
  export type ObjectStoreUrl = Branded<string, 'PFrameInternal.ObjectStoreUrl'>;
114
75
 
76
+ /** HTTP(S) request handler creation options */
77
+ export type RequestHandlerOptions = {
78
+ /** Object store to serve files from, @see HttpHelpers.createFsStore */
79
+ store: ObjectStore;
80
+ /** Here will go caching options... */
81
+ }
82
+
115
83
  /** Server configuration options */
116
84
  export type HttpServerOptions = {
117
- /** HTTP request handler function */
85
+ /** HTTP(S) request handler function, @see HttpHelpers.createRequestHandler */
118
86
  handler: RequestListener;
119
- /** Host to bind to (defaults to '127.0.0.1') */
120
- host?: string;
121
- /** Port to bind to (defaults to 0 for auto-assignment) */
87
+ /** Port to bind to (@default 0 for auto-assignment) */
122
88
  port?: number;
123
- /** AbortSignal to stop the server */
124
- signal: AbortSignal;
89
+ /** Do not apply authorization middleware to @param handler */
90
+ noAuth?: true;
91
+ /** Downgrade default HTTPS server to plain HTTP, @warning use only for testing */
92
+ http?: true;
125
93
  };
126
94
 
127
- /** Result of the server start operation */
128
- export type HttpServerStartResult = {
129
- /** Server address info */
130
- address: AddressInfo;
95
+ /**
96
+ * Long unique opaque string for use in Bearer authorization header
97
+ *
98
+ * @example
99
+ * ```ts
100
+ * request.setHeader('Authorization', `Bearer ${authToken}`);
101
+ * ```
102
+ */
103
+ export type HttpAuthorizationToken = Branded<string, 'PFrameInternal.HttpAuthorizationToken'>;
104
+
105
+ /**
106
+ * TLS certificate in PEM format
107
+ *
108
+ * @example
109
+ * ```txt
110
+ * -----BEGIN CERTIFICATE-----
111
+ * MIIC2zCCAcOgAwIBAgIJaVW7...
112
+ * ...
113
+ * ...Yf9CRK8fgnukKM7TJ
114
+ * -----END CERTIFICATE-----
115
+ * ```
116
+ */
117
+ export type PemCertificate = Branded<string, 'PFrameInternal.PemCertificate'>;
118
+
119
+ /** HTTP(S) server information and controls, @see HttpHelpers.createHttpServer */
120
+ export interface HttpServer {
121
+ /** Server address info formatted as `http{s}://<host>:<port>/` */
122
+ get address(): ObjectStoreUrl;
123
+ /** Authorization token for Bearer scheme, undefined when @see HttpServerOptions.noAuth flag is set */
124
+ get authToken(): HttpAuthorizationToken | undefined;
125
+ /** Base64-encoded CA certificate in PEM format, undefined when @see HttpServerOptions.http flag is set */
126
+ get encodedCaCert(): Base64Encoded<PemCertificate> | undefined;
131
127
  /** Promise that resolves when the server is stopped */
132
- stopped: Promise<void>;
133
- };
128
+ get stopped(): Promise<void>;
129
+ /** Request server stop, returns the same promise as @see HttpServer.stopped */
130
+ stop(): Promise<void>;
131
+ }
134
132
 
133
+ /** List of HTTP(S) related helper functions exposed by PFrame module */
135
134
  export interface HttpHelpers {
136
135
  /**
137
136
  * Create an object store for serving files from a local directory.
138
137
  * Rejects if the provided path does not exist or is not a directory.
139
- * Intended for testing purposes, you will probably want to implement a different store.
140
138
  */
141
139
  createFsStore(rootDir: string): Promise<ObjectStore>;
142
140
 
143
141
  /**
144
142
  * Create an HTTP request handler for serving files from an object store.
145
- * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise.
143
+ * Accepts only paths of the form `/<filename>.parquet`, returns 410 otherwise.
146
144
  * Assumes that files are immutable (and sets cache headers accordingly).
147
145
  */
148
- createRequestHandler(store: ObjectStore): RequestListener;
149
-
150
- /**
151
- * Create an object store URL from the server address info.
152
- * Result of this function is intended to be passed to PFrames as data source parquet prefix.
153
- */
154
- createObjectStoreUrl(info: AddressInfo): ObjectStoreUrl;
146
+ createRequestHandler(options: RequestHandlerOptions): RequestListener;
155
147
 
156
148
  /**
157
- * Serve HTTP requests using the provided handler on the given host and port.
158
- * Returns a promise that resolves when the server is stopped.
149
+ * Serve HTTP(S) requests using the provided handler on localhost port.
150
+ * @returns promise that resolves when the server has stopped.
159
151
  *
160
152
  * @example
161
153
  * ```ts
162
- * const abortController = new AbortController();
163
154
  * const rootDir = '/path/to/directory/with/parquet/files';
164
- * const port = 3000;
165
155
  *
166
156
  * let store = await HttpHelpers.createFsStore(rootDir).catch((err: unknown) => {
167
157
  * throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);
168
158
  * });
169
159
  *
170
- * const { address: serverAddress, stopped: serverStopped } = await HttpHelpers.serve({
160
+ * const server = await HttpHelpers.createHttpServer({
171
161
  * handler: HttpHelpers.createRequestHandler(store),
172
- * port,
173
- * signal: abortController.signal
174
162
  * }).catch((err: unknown) => {
175
- * throw new Error(`Failed to start http server on port ${port} - ${ensureError(err)}`);
163
+ * throw new Error(`Failed to start HTTP server - ${ensureError(err)}`);
176
164
  * });
177
165
  *
178
- * const _ = HttpHelpers.createObjectStoreUrl(serverAddress);
166
+ * const { address, authToken, base64EncodedCaCert } = server;
179
167
  *
180
- * abortController.abort();
181
- * await serverStopped;
168
+ * await server.stop();
182
169
  * ```
183
170
  */
184
- serve(options: HttpServerOptions): Promise<HttpServerStartResult>;
171
+ createHttpServer(options: HttpServerOptions): Promise<HttpServer>;
185
172
  }