@milaboratories/pl-model-middle-layer 1.8.11 → 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 +69 -80
  2. package/dist/pframe/internal_api/http_helpers.d.ts.map +1 -1
  3. package/package.json +7 -7
  4. package/src/pframe/internal_api/http_helpers.ts +74 -84
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,131 +16,129 @@ 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;
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;
116
86
  };
117
- /** Result of the server start operation */
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 */
118
110
  export interface HttpServer {
119
- /** Server address info */
120
- get address(): AddressInfo;
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;
121
117
  /** Promise that resolves when the server is stopped */
122
118
  get stopped(): Promise<void>;
123
- /** Stop the server */
119
+ /** Request server stop, returns the same promise as @see HttpServer.stopped */
124
120
  stop(): Promise<void>;
125
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
141
  * const rootDir = '/path/to/directory/with/parquet/files';
151
- * const port = 3000;
152
142
  *
153
143
  * let store = await HttpHelpers.createFsStore(rootDir).catch((err: unknown) => {
154
144
  * throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);
@@ -156,12 +146,11 @@ export interface HttpHelpers {
156
146
  *
157
147
  * const server = await HttpHelpers.createHttpServer({
158
148
  * handler: HttpHelpers.createRequestHandler(store),
159
- * port,
160
149
  * }).catch((err: unknown) => {
161
- * throw new Error(`Failed to start http server on port ${port} - ${ensureError(err)}`);
150
+ * throw new Error(`Failed to start HTTP server - ${ensureError(err)}`);
162
151
  * });
163
152
  *
164
- * const _ = HttpHelpers.createObjectStoreUrl(server.address);
153
+ * const { address, authToken, base64EncodedCaCert } = server;
165
154
  *
166
155
  * await server.stop();
167
156
  * ```
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;CACf,CAAC;AAEF,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,0BAA0B;IAC1B,IAAI,OAAO,IAAI,WAAW,CAAC;IAC3B,uDAAuD;IACvD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,sBAAsB;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,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;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,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.11",
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.12"
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",
28
- "@milaboratories/ts-builder": "1.0.4",
29
- "@milaboratories/ts-configs": "1.0.6"
27
+ "@milaboratories/ts-builder": "1.0.5",
28
+ "@milaboratories/ts-configs": "1.0.6",
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,140 +18,140 @@ export type FileRange = {
27
18
  */
28
19
  export interface ObjectStore {
29
20
  /**
30
- * Check if file exists
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)
31
23
  *
32
24
  * @example
33
25
  * ```ts
34
- * async fileExists(filename: string): Promise<boolean> {
26
+ * async getFileSize(filename: string): Promise<number> {
35
27
  * 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
49
- *
50
- * @example
51
- * ```ts
52
- * async getFileStats(filename: string): Promise<FileStats> {
53
- * 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;
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;
123
93
  };
124
94
 
125
- /** Result of the server start operation */
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 */
126
120
  export interface HttpServer {
127
- /** Server address info */
128
- get address(): AddressInfo;
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;
129
127
  /** Promise that resolves when the server is stopped */
130
128
  get stopped(): Promise<void>;
131
- /** Stop the server */
129
+ /** Request server stop, returns the same promise as @see HttpServer.stopped */
132
130
  stop(): Promise<void>;
133
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
154
  * const rootDir = '/path/to/directory/with/parquet/files';
163
- * const port = 3000;
164
155
  *
165
156
  * let store = await HttpHelpers.createFsStore(rootDir).catch((err: unknown) => {
166
157
  * throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);
@@ -168,12 +159,11 @@ export interface HttpHelpers {
168
159
  *
169
160
  * const server = await HttpHelpers.createHttpServer({
170
161
  * handler: HttpHelpers.createRequestHandler(store),
171
- * port,
172
162
  * }).catch((err: unknown) => {
173
- * throw new Error(`Failed to start http server on port ${port} - ${ensureError(err)}`);
163
+ * throw new Error(`Failed to start HTTP server - ${ensureError(err)}`);
174
164
  * });
175
165
  *
176
- * const _ = HttpHelpers.createObjectStoreUrl(server.address);
166
+ * const { address, authToken, base64EncodedCaCert } = server;
177
167
  *
178
168
  * await server.stop();
179
169
  * ```