@twin.org/node-core 0.0.2-next.25 → 0.0.2-next.27
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/README.md +1 -1
- package/dist/es/bootstrap.js +374 -0
- package/dist/es/bootstrap.js.map +1 -0
- package/dist/es/builders/engineEnvBuilder.js +1051 -0
- package/dist/es/builders/engineEnvBuilder.js.map +1 -0
- package/dist/es/builders/engineServerEnvBuilder.js +197 -0
- package/dist/es/builders/engineServerEnvBuilder.js.map +1 -0
- package/dist/es/builders/extensionsBuilder.js +100 -0
- package/dist/es/builders/extensionsBuilder.js.map +1 -0
- package/dist/es/defaults.js +9 -0
- package/dist/es/defaults.js.map +1 -0
- package/dist/es/identity.js +169 -0
- package/dist/es/identity.js.map +1 -0
- package/dist/es/index.js +23 -0
- package/dist/es/index.js.map +1 -0
- package/dist/es/models/ICacheMetadata.js +4 -0
- package/dist/es/models/ICacheMetadata.js.map +1 -0
- package/dist/es/models/IEngineEnvironmentVariables.js +4 -0
- package/dist/es/models/IEngineEnvironmentVariables.js.map +1 -0
- package/dist/es/models/IEngineServerEnvironmentVariables.js +2 -0
- package/dist/es/models/IEngineServerEnvironmentVariables.js.map +1 -0
- package/dist/es/models/IModuleProtocol.js +2 -0
- package/dist/es/models/IModuleProtocol.js.map +1 -0
- package/dist/es/models/INodeEngineConfig.js +2 -0
- package/dist/es/models/INodeEngineConfig.js.map +1 -0
- package/dist/es/models/INodeEngineState.js +2 -0
- package/dist/es/models/INodeEngineState.js.map +1 -0
- package/dist/es/models/INodeEnvironmentVariables.js +2 -0
- package/dist/es/models/INodeEnvironmentVariables.js.map +1 -0
- package/dist/es/models/INodeOptions.js +2 -0
- package/dist/es/models/INodeOptions.js.map +1 -0
- package/dist/es/models/IProtocolHandlerResult.js +4 -0
- package/dist/es/models/IProtocolHandlerResult.js.map +1 -0
- package/dist/es/models/moduleProtocol.js +29 -0
- package/dist/es/models/moduleProtocol.js.map +1 -0
- package/dist/es/models/nodeExtensionMethods.js +2 -0
- package/dist/es/models/nodeExtensionMethods.js.map +1 -0
- package/dist/es/models/nodeFeatures.js +21 -0
- package/dist/es/models/nodeFeatures.js.map +1 -0
- package/dist/es/node.js +265 -0
- package/dist/es/node.js.map +1 -0
- package/dist/es/server.js +74 -0
- package/dist/es/server.js.map +1 -0
- package/dist/es/utils.js +418 -0
- package/dist/es/utils.js.map +1 -0
- package/dist/types/bootstrap.d.ts +27 -10
- package/dist/types/builders/engineEnvBuilder.d.ts +3 -2
- package/dist/types/builders/engineServerEnvBuilder.d.ts +3 -2
- package/dist/types/builders/extensionsBuilder.d.ts +2 -2
- package/dist/types/identity.d.ts +14 -0
- package/dist/types/index.d.ts +20 -15
- package/dist/types/models/ICacheMetadata.d.ts +17 -0
- package/dist/types/models/IEngineEnvironmentVariables.d.ts +12 -5
- package/dist/types/models/IEngineServerEnvironmentVariables.d.ts +1 -1
- package/dist/types/models/IModuleProtocol.d.ts +18 -0
- package/dist/types/models/INodeEngineState.d.ts +22 -0
- package/dist/types/models/INodeEnvironmentVariables.d.ts +49 -8
- package/dist/types/models/INodeOptions.d.ts +13 -3
- package/dist/types/models/IProtocolHandlerResult.d.ts +13 -0
- package/dist/types/models/moduleProtocol.d.ts +29 -0
- package/dist/types/models/nodeExtensionMethods.d.ts +2 -2
- package/dist/types/models/nodeFeatures.d.ts +5 -5
- package/dist/types/node.d.ts +17 -7
- package/dist/types/server.d.ts +7 -6
- package/dist/types/utils.d.ts +69 -2
- package/docs/changelog.md +7 -0
- package/docs/detailed-guide.md +129 -0
- package/docs/reference/functions/bootstrap.md +1 -1
- package/docs/reference/functions/bootstrapAuth.md +1 -1
- package/docs/reference/functions/bootstrapBlobEncryption.md +1 -1
- package/docs/reference/functions/bootstrapContextIdHandlers.md +35 -0
- package/docs/reference/functions/bootstrapImmutableProofMethod.md +1 -1
- package/docs/reference/functions/{bootstrapNodeUser.md → bootstrapNodeAdminUser.md} +3 -3
- package/docs/reference/functions/{bootstrapNodeIdentity.md → bootstrapNodeId.md} +3 -3
- package/docs/reference/functions/bootstrapSynchronisedStorage.md +1 -1
- package/docs/reference/functions/bootstrapTenantId.md +35 -0
- package/docs/reference/functions/buildConfiguration.md +2 -2
- package/docs/reference/functions/buildEngineConfiguration.md +7 -1
- package/docs/reference/functions/buildEngineServerConfiguration.md +7 -1
- package/docs/reference/functions/createModuleImportUrl.md +21 -0
- package/docs/reference/functions/getExtensionsCacheDir.md +31 -0
- package/docs/reference/functions/handleHttpsProtocol.md +49 -0
- package/docs/reference/functions/handleNpmProtocol.md +31 -0
- package/docs/reference/functions/hashUrl.md +19 -0
- package/docs/reference/functions/isCacheExpired.md +31 -0
- package/docs/reference/functions/overrideModuleImport.md +8 -2
- package/docs/reference/functions/parseModuleProtocol.md +19 -0
- package/docs/reference/functions/resolvePackageEntryPoint.md +32 -0
- package/docs/reference/functions/run.md +3 -3
- package/docs/reference/functions/start.md +8 -2
- package/docs/reference/index.md +18 -2
- package/docs/reference/interfaces/ICacheMetadata.md +27 -0
- package/docs/reference/interfaces/IEngineEnvironmentVariables.md +24 -9
- package/docs/reference/interfaces/IEngineServerEnvironmentVariables.md +36 -13
- package/docs/reference/interfaces/IModuleProtocol.md +27 -0
- package/docs/reference/interfaces/INodeEngineConfig.md +430 -0
- package/docs/reference/interfaces/INodeEngineState.md +39 -0
- package/docs/reference/interfaces/INodeEnvironmentVariables.md +149 -24
- package/docs/reference/interfaces/INodeOptions.md +21 -1
- package/docs/reference/interfaces/IProtocolHandlerResult.md +19 -0
- package/docs/reference/type-aliases/ModuleProtocol.md +5 -0
- package/docs/reference/variables/ModuleProtocol.md +37 -0
- package/docs/reference/variables/NodeFeatures.md +7 -7
- package/locales/en.json +20 -8
- package/package.json +40 -8
- package/dist/cjs/index.cjs +0 -2232
- package/dist/esm/index.mjs +0 -2179
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Metadata for cached HTTPS extensions.
|
|
3
|
+
*/
|
|
4
|
+
export interface ICacheMetadata {
|
|
5
|
+
/**
|
|
6
|
+
* Timestamp when the file was downloaded.
|
|
7
|
+
*/
|
|
8
|
+
downloadedAt: number;
|
|
9
|
+
/**
|
|
10
|
+
* Original URL of the cached file.
|
|
11
|
+
*/
|
|
12
|
+
url: string;
|
|
13
|
+
/**
|
|
14
|
+
* Size of the cached file in bytes.
|
|
15
|
+
*/
|
|
16
|
+
size: number;
|
|
17
|
+
}
|
|
@@ -14,6 +14,18 @@ export interface IEngineEnvironmentVariables {
|
|
|
14
14
|
* The name of the state file.
|
|
15
15
|
*/
|
|
16
16
|
stateFilename?: string;
|
|
17
|
+
/**
|
|
18
|
+
* Is multi-tenant support enabled, defaults to false.
|
|
19
|
+
*/
|
|
20
|
+
tenantEnabled?: string;
|
|
21
|
+
/**
|
|
22
|
+
* A tenant id to use as a default for the node.
|
|
23
|
+
*/
|
|
24
|
+
tenantId?: string;
|
|
25
|
+
/**
|
|
26
|
+
* A tenant api key to use as a default for the node.
|
|
27
|
+
*/
|
|
28
|
+
tenantApiKey?: string;
|
|
17
29
|
/**
|
|
18
30
|
* The type of the entity storage to create, comma separate for more than one connector.
|
|
19
31
|
* values: file, memory, aws-dynamodb, azure-cosmosdb, gcp-firestoredb, scylladb, mysql, mongodb, postgresql
|
|
@@ -285,11 +297,6 @@ export interface IEngineEnvironmentVariables {
|
|
|
285
297
|
* Are the messaging components enabled, defaults to false.
|
|
286
298
|
*/
|
|
287
299
|
messagingEnabled?: string;
|
|
288
|
-
/**
|
|
289
|
-
* An initial set of templates for the messages.
|
|
290
|
-
* Use the @json: prefix to specify the path to the JSON file.
|
|
291
|
-
*/
|
|
292
|
-
messagingTemplates?: string;
|
|
293
300
|
/**
|
|
294
301
|
* AWS SES region.
|
|
295
302
|
*/
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { ModuleProtocol } from "./moduleProtocol.js";
|
|
2
|
+
/**
|
|
3
|
+
* The parsed module protocol information.
|
|
4
|
+
*/
|
|
5
|
+
export interface IModuleProtocol {
|
|
6
|
+
/**
|
|
7
|
+
* The protocol type.
|
|
8
|
+
*/
|
|
9
|
+
protocol: ModuleProtocol;
|
|
10
|
+
/**
|
|
11
|
+
* The identifier after the protocol (or the original if no protocol).
|
|
12
|
+
*/
|
|
13
|
+
identifier: string;
|
|
14
|
+
/**
|
|
15
|
+
* The original module string.
|
|
16
|
+
*/
|
|
17
|
+
original: string;
|
|
18
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { IEngineState } from "@twin.org/engine-models";
|
|
2
|
+
/**
|
|
3
|
+
* The engine state for the node.
|
|
4
|
+
*/
|
|
5
|
+
export interface INodeEngineState extends IEngineState {
|
|
6
|
+
/**
|
|
7
|
+
* The identity for the node.
|
|
8
|
+
*/
|
|
9
|
+
nodeId?: string;
|
|
10
|
+
/**
|
|
11
|
+
* The tenant id for the node.
|
|
12
|
+
*/
|
|
13
|
+
nodeTenantId?: string;
|
|
14
|
+
/**
|
|
15
|
+
* The identity for the organization.
|
|
16
|
+
*/
|
|
17
|
+
nodeOrganizationId?: string;
|
|
18
|
+
/**
|
|
19
|
+
* The identity for the admin user.
|
|
20
|
+
*/
|
|
21
|
+
nodeAdminUserId?: string;
|
|
22
|
+
}
|
|
@@ -1,28 +1,69 @@
|
|
|
1
|
-
import type { IEngineServerEnvironmentVariables } from "./IEngineServerEnvironmentVariables";
|
|
1
|
+
import type { IEngineServerEnvironmentVariables } from "./IEngineServerEnvironmentVariables.js";
|
|
2
2
|
/**
|
|
3
3
|
* The environment variables for the node.
|
|
4
4
|
*/
|
|
5
5
|
export interface INodeEnvironmentVariables extends IEngineServerEnvironmentVariables {
|
|
6
6
|
/**
|
|
7
7
|
* The features that are enabled on the node.
|
|
8
|
-
* @default [
|
|
8
|
+
* @default []
|
|
9
9
|
*/
|
|
10
10
|
features?: string;
|
|
11
11
|
/**
|
|
12
12
|
* The identity of the node which, if empty and node-identity feature is enabled it will be generated.
|
|
13
13
|
*/
|
|
14
|
-
|
|
14
|
+
nodeIdentity?: string;
|
|
15
15
|
/**
|
|
16
16
|
* The mnemonic for the identity, if empty and node-identity feature is enabled it will be randomly generated.
|
|
17
17
|
*/
|
|
18
|
-
|
|
18
|
+
nodeMnemonic?: string;
|
|
19
19
|
/**
|
|
20
|
-
* If the node-user feature is enabled, this will be the
|
|
20
|
+
* If the node-admin-user feature is enabled, this will be the organization of the user, if one is not provided it will be generated
|
|
21
|
+
*/
|
|
22
|
+
organizationIdentity?: string;
|
|
23
|
+
/**
|
|
24
|
+
* The mnemonic for the organization, if empty and node-admin-user feature is enabled it will be randomly generated.
|
|
25
|
+
*/
|
|
26
|
+
organizationMnemonic?: string;
|
|
27
|
+
/**
|
|
28
|
+
* If the node-admin-user feature is enabled, this will be the identity of the user, if one is not provided it will be generated
|
|
29
|
+
*/
|
|
30
|
+
adminUserIdentity?: string;
|
|
31
|
+
/**
|
|
32
|
+
* The mnemonic for the admin user, if empty and node-admin-user feature is enabled it will be randomly generated.
|
|
33
|
+
*/
|
|
34
|
+
adminUserMnemonic?: string;
|
|
35
|
+
/**
|
|
36
|
+
* If the node-admin-user feature is enabled, this will be the name of the user.
|
|
21
37
|
* @default admin@node
|
|
22
38
|
*/
|
|
23
|
-
|
|
39
|
+
adminUserName?: string;
|
|
40
|
+
/**
|
|
41
|
+
* If the node-admin-user feature is enabled, this will be the password of the user, if empty it will be randomly generated.
|
|
42
|
+
*/
|
|
43
|
+
adminUserPassword?: string;
|
|
44
|
+
/**
|
|
45
|
+
* Maximum size in MB for HTTPS extensions downloads.
|
|
46
|
+
* @default 10
|
|
47
|
+
*/
|
|
48
|
+
extensionsMaxSizeMb?: number;
|
|
49
|
+
/**
|
|
50
|
+
* Whether to clear the extensions cache on startup.
|
|
51
|
+
* @default false
|
|
52
|
+
*/
|
|
53
|
+
extensionsClearCache?: boolean;
|
|
54
|
+
/**
|
|
55
|
+
* Custom directory for extensions cache storage.
|
|
56
|
+
* @default ".tmp"
|
|
57
|
+
*/
|
|
58
|
+
extensionsCacheDirectory?: string;
|
|
59
|
+
/**
|
|
60
|
+
* TTL in hours for HTTPS extensions cache.
|
|
61
|
+
* @default 24
|
|
62
|
+
*/
|
|
63
|
+
extensionsCacheTtlHours?: number;
|
|
24
64
|
/**
|
|
25
|
-
*
|
|
65
|
+
* Force refresh of all cached extensions.
|
|
66
|
+
* @default false
|
|
26
67
|
*/
|
|
27
|
-
|
|
68
|
+
extensionsForceRefresh?: boolean;
|
|
28
69
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { IEngineCore, IEngineServer, IEngineStateStorage } from "@twin.org/engine-models";
|
|
2
2
|
import type { IEngineConfig } from "@twin.org/engine-types";
|
|
3
|
-
import type { INodeEngineConfig } from "./INodeEngineConfig";
|
|
4
|
-
import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables";
|
|
3
|
+
import type { INodeEngineConfig } from "./INodeEngineConfig.js";
|
|
4
|
+
import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables.js";
|
|
5
5
|
/**
|
|
6
6
|
* The options when running the node.
|
|
7
7
|
*/
|
|
@@ -15,12 +15,18 @@ export interface INodeOptions {
|
|
|
15
15
|
* The version of the server, defaults to the current version.
|
|
16
16
|
*/
|
|
17
17
|
serverVersion?: string;
|
|
18
|
+
/**
|
|
19
|
+
* Additional environment variables to set.
|
|
20
|
+
*/
|
|
21
|
+
envVars?: {
|
|
22
|
+
[key: string]: string;
|
|
23
|
+
};
|
|
18
24
|
/**
|
|
19
25
|
* Additional environment variable filenames to load, defaults to .env.
|
|
20
26
|
*/
|
|
21
27
|
envFilenames?: string[];
|
|
22
28
|
/**
|
|
23
|
-
* The prefix for environment variables, defaults to "
|
|
29
|
+
* The prefix for environment variables, defaults to "TWIN_".
|
|
24
30
|
*/
|
|
25
31
|
envPrefix?: string;
|
|
26
32
|
/**
|
|
@@ -71,4 +77,8 @@ export interface INodeOptions {
|
|
|
71
77
|
* If not provided, a default file-based state storage will be used.
|
|
72
78
|
*/
|
|
73
79
|
stateStorage?: IEngineStateStorage;
|
|
80
|
+
/**
|
|
81
|
+
* Disables process.exit calls on fatal errors and throws instead.
|
|
82
|
+
*/
|
|
83
|
+
disableProcessExitOnFailure?: boolean;
|
|
74
84
|
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The protocol types for modules.
|
|
3
|
+
*/
|
|
4
|
+
export declare const ModuleProtocol: {
|
|
5
|
+
/**
|
|
6
|
+
* Local module (starts with . or / or file://).
|
|
7
|
+
*/
|
|
8
|
+
readonly Local: "local";
|
|
9
|
+
/**
|
|
10
|
+
* NPM package (starts with npm:).
|
|
11
|
+
*/
|
|
12
|
+
readonly Npm: "npm";
|
|
13
|
+
/**
|
|
14
|
+
* HTTPS URL (starts with https://).
|
|
15
|
+
*/
|
|
16
|
+
readonly Https: "https";
|
|
17
|
+
/**
|
|
18
|
+
* HTTP URL (starts with http://).
|
|
19
|
+
*/
|
|
20
|
+
readonly Http: "http";
|
|
21
|
+
/**
|
|
22
|
+
* Default/standard module resolution.
|
|
23
|
+
*/
|
|
24
|
+
readonly Default: "default";
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* The protocol type for a module.
|
|
28
|
+
*/
|
|
29
|
+
export type ModuleProtocol = (typeof ModuleProtocol)[keyof typeof ModuleProtocol];
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { IEngineCore, IEngineServer } from "@twin.org/engine-models";
|
|
2
|
-
import type { INodeEngineConfig } from "./INodeEngineConfig";
|
|
3
|
-
import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables";
|
|
2
|
+
import type { INodeEngineConfig } from "./INodeEngineConfig.js";
|
|
3
|
+
import type { INodeEnvironmentVariables } from "./INodeEnvironmentVariables.js";
|
|
4
4
|
/**
|
|
5
5
|
* The type for the initialise method of an extension module.
|
|
6
6
|
* @param envVars The environment variables for the node.
|
|
@@ -3,15 +3,15 @@
|
|
|
3
3
|
*/
|
|
4
4
|
export declare const NodeFeatures: {
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
6
|
+
* NodeId - generates an identity for the node if not provided in config.
|
|
7
7
|
*/
|
|
8
|
-
readonly
|
|
8
|
+
readonly NodeId: "node-identity";
|
|
9
9
|
/**
|
|
10
|
-
*
|
|
10
|
+
* NodeAdminUser - generates an admin user for the node if not provided in config.
|
|
11
11
|
*/
|
|
12
|
-
readonly
|
|
12
|
+
readonly NodeAdminUser: "node-admin-user";
|
|
13
13
|
/**
|
|
14
|
-
* NodeWallet - generates
|
|
14
|
+
* NodeWallet - generates wallets for any identities that need them.
|
|
15
15
|
*/
|
|
16
16
|
readonly NodeWallet: "node-wallet";
|
|
17
17
|
};
|
package/dist/types/node.d.ts
CHANGED
|
@@ -1,13 +1,21 @@
|
|
|
1
1
|
import type { IServerInfo } from "@twin.org/api-models";
|
|
2
|
-
import type {
|
|
3
|
-
import type {
|
|
4
|
-
import type {
|
|
2
|
+
import type { Engine } from "@twin.org/engine";
|
|
3
|
+
import type { EngineServer } from "@twin.org/engine-server";
|
|
4
|
+
import type { IEngineServerConfig } from "@twin.org/engine-server-types";
|
|
5
|
+
import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
|
|
6
|
+
import type { INodeEngineState } from "./models/INodeEngineState.js";
|
|
7
|
+
import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
|
|
8
|
+
import type { INodeOptions } from "./models/INodeOptions.js";
|
|
5
9
|
/**
|
|
6
10
|
* Run the TWIN Node server.
|
|
7
11
|
* @param nodeOptions Optional configuration options for running the server.
|
|
8
|
-
* @returns A promise that resolves when the server is started.
|
|
12
|
+
* @returns A promise that resolves when the server is started containing a shutdown method.
|
|
9
13
|
*/
|
|
10
|
-
export declare function run(nodeOptions?: INodeOptions): Promise<
|
|
14
|
+
export declare function run(nodeOptions?: INodeOptions): Promise<{
|
|
15
|
+
engine: Engine<IEngineServerConfig, INodeEngineState>;
|
|
16
|
+
server: EngineServer;
|
|
17
|
+
shutdown: () => Promise<void>;
|
|
18
|
+
} | undefined>;
|
|
11
19
|
/**
|
|
12
20
|
* Build the configuration for the TWIN Node server.
|
|
13
21
|
* @param processEnv The environment variables from the process.
|
|
@@ -23,9 +31,11 @@ export declare function buildConfiguration(processEnv: {
|
|
|
23
31
|
[id: string]: string | unknown;
|
|
24
32
|
};
|
|
25
33
|
nodeEngineConfig: INodeEngineConfig;
|
|
34
|
+
contextIdKeys: string[];
|
|
26
35
|
}>;
|
|
27
36
|
/**
|
|
28
|
-
* Override module imports to
|
|
37
|
+
* Override module imports to support protocol-based loading (npm:, https:) and local files.
|
|
29
38
|
* @param executionDirectory The execution directory for resolving local module paths.
|
|
39
|
+
* @param envVars The environment variables containing extension configuration (optional, uses defaults if not provided).
|
|
30
40
|
*/
|
|
31
|
-
export declare function overrideModuleImport(executionDirectory: string): void;
|
|
41
|
+
export declare function overrideModuleImport(executionDirectory: string, envVars?: INodeEnvironmentVariables): void;
|
package/dist/types/server.d.ts
CHANGED
|
@@ -1,19 +1,20 @@
|
|
|
1
1
|
import { Engine } from "@twin.org/engine";
|
|
2
|
-
import { type IEngineState } from "@twin.org/engine-models";
|
|
3
2
|
import { EngineServer } from "@twin.org/engine-server";
|
|
4
3
|
import type { IEngineServerConfig } from "@twin.org/engine-server-types";
|
|
5
|
-
import type { INodeEngineConfig } from "./models/INodeEngineConfig";
|
|
6
|
-
import type {
|
|
7
|
-
import type {
|
|
4
|
+
import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
|
|
5
|
+
import type { INodeEngineState } from "./models/INodeEngineState.js";
|
|
6
|
+
import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
|
|
7
|
+
import type { INodeOptions } from "./models/INodeOptions.js";
|
|
8
8
|
/**
|
|
9
9
|
* Start the engine server.
|
|
10
10
|
* @param nodeOptions Optional run options for the engine server.
|
|
11
11
|
* @param nodeEngineConfig The configuration for the engine server.
|
|
12
12
|
* @param envVars The environment variables.
|
|
13
|
+
* @param contextIdKeys The context ID keys.
|
|
13
14
|
* @returns The engine server.
|
|
14
15
|
*/
|
|
15
|
-
export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables): Promise<{
|
|
16
|
-
engine: Engine<IEngineServerConfig,
|
|
16
|
+
export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables, contextIdKeys?: string[]): Promise<{
|
|
17
|
+
engine: Engine<IEngineServerConfig, INodeEngineState>;
|
|
17
18
|
server: EngineServer;
|
|
18
19
|
shutdown: () => Promise<void>;
|
|
19
20
|
} | undefined>;
|
package/dist/types/utils.d.ts
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
|
-
import type {
|
|
2
|
-
import {
|
|
1
|
+
import type { IModuleProtocol } from "./models/IModuleProtocol.js";
|
|
2
|
+
import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
|
|
3
|
+
import type { IProtocolHandlerResult } from "./models/IProtocolHandlerResult.js";
|
|
4
|
+
import { ModuleProtocol } from "./models/moduleProtocol.js";
|
|
5
|
+
import { NodeFeatures } from "./models/nodeFeatures.js";
|
|
3
6
|
/**
|
|
4
7
|
* Initialise the locales for the application.
|
|
5
8
|
* @param localesDirectory The directory containing the locales.
|
|
@@ -52,3 +55,67 @@ export declare function loadJsonFile<T>(filename: string): Promise<T>;
|
|
|
52
55
|
* @returns The features that are enabled on the node.
|
|
53
56
|
*/
|
|
54
57
|
export declare function getFeatures(env: INodeEnvironmentVariables): NodeFeatures[];
|
|
58
|
+
/**
|
|
59
|
+
* Parse the protocol from a module name.
|
|
60
|
+
* @param moduleName The module name to parse.
|
|
61
|
+
* @returns The parsed protocol information.
|
|
62
|
+
*/
|
|
63
|
+
export declare function parseModuleProtocol(moduleName: string): IModuleProtocol;
|
|
64
|
+
/**
|
|
65
|
+
* Hash a URL to create a safe filename.
|
|
66
|
+
* @param url The URL to hash.
|
|
67
|
+
* @returns A hashed filename safe for the filesystem.
|
|
68
|
+
*/
|
|
69
|
+
export declare function hashUrl(url: string): string;
|
|
70
|
+
/**
|
|
71
|
+
* Get the extensions cache directory.
|
|
72
|
+
* @param executionDirectory The execution directory.
|
|
73
|
+
* @param protocol The protocol type for subdirectory organization.
|
|
74
|
+
* @param cacheDirectory The cache directory base path.
|
|
75
|
+
* @returns The cache directory path.
|
|
76
|
+
*/
|
|
77
|
+
export declare function getExtensionsCacheDir(executionDirectory: string, protocol: ModuleProtocol, cacheDirectory?: string): string;
|
|
78
|
+
/**
|
|
79
|
+
* Handle the npm: protocol by installing the package if needed.
|
|
80
|
+
* @param packageName The npm package name (without npm: prefix).
|
|
81
|
+
* @param executionDirectory The execution directory.
|
|
82
|
+
* @param cacheDirectory The cache directory base path.
|
|
83
|
+
* @returns The resolved path to the installed module.
|
|
84
|
+
*/
|
|
85
|
+
export declare function handleNpmProtocol(packageName: string, executionDirectory: string, cacheDirectory?: string): Promise<IProtocolHandlerResult>;
|
|
86
|
+
/**
|
|
87
|
+
* Check if a cached file has expired based on TTL and force refresh settings.
|
|
88
|
+
* @param metadataPath Path to the cache metadata file.
|
|
89
|
+
* @param ttlHours Time to live in hours.
|
|
90
|
+
* @param forceRefresh Whether to force refresh regardless of TTL.
|
|
91
|
+
* @returns True if the cache is expired or should be refreshed.
|
|
92
|
+
*/
|
|
93
|
+
export declare function isCacheExpired(metadataPath: string, ttlHours: number, forceRefresh: boolean): Promise<boolean>;
|
|
94
|
+
/**
|
|
95
|
+
* Handle the https: protocol by downloading the module if needed.
|
|
96
|
+
* @param url The HTTPS URL to download from.
|
|
97
|
+
* @param executionDirectory The execution directory.
|
|
98
|
+
* @param maxSizeMb The maximum size in MB for the download.
|
|
99
|
+
* @param cacheDirectory The cache directory base path.
|
|
100
|
+
* @param ttlHours TTL in hours for cache expiration.
|
|
101
|
+
* @param forceRefresh Whether to force refresh the cache.
|
|
102
|
+
* @returns The resolved path to the downloaded module.
|
|
103
|
+
*/
|
|
104
|
+
export declare function handleHttpsProtocol(url: string, executionDirectory: string, maxSizeMb: number, cacheDirectory?: string, ttlHours?: number, forceRefresh?: boolean): Promise<IProtocolHandlerResult>;
|
|
105
|
+
/**
|
|
106
|
+
* Resolve the main entry point from a package directory using Node.js resolution with fallback.
|
|
107
|
+
* Uses require.resolve() when possible for standard Node.js behavior, with manual fallback.
|
|
108
|
+
* @param packagePath The absolute path to the package directory.
|
|
109
|
+
* @param packageName The package name for require.resolve().
|
|
110
|
+
* @param fallback The fallback file name if no entry point is found.
|
|
111
|
+
* @returns The resolved entry point file name (relative to package directory).
|
|
112
|
+
*/
|
|
113
|
+
export declare function resolvePackageEntryPoint(packagePath: string, packageName: string, fallback?: string): Promise<string>;
|
|
114
|
+
/**
|
|
115
|
+
* Convert a file path to an import-compatible URL for cross-platform module loading.
|
|
116
|
+
* On Windows, adds the 'file://' protocol prefix required for dynamic imports.
|
|
117
|
+
* On other platforms, returns the path unchanged.
|
|
118
|
+
* @param filePath The absolute file path to convert.
|
|
119
|
+
* @returns A URL string compatible with dynamic import().
|
|
120
|
+
*/
|
|
121
|
+
export declare function createModuleImportUrl(filePath: string): string;
|
package/docs/changelog.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# @twin.org/node-core - Changelog
|
|
2
2
|
|
|
3
|
+
## [0.0.2-next.26](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.25...node-core-v0.0.2-next.26) (2025-10-10)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* adding npm and https protocols to load extensions ([#45](https://github.com/twinfoundation/node/issues/45)) ([33940b7](https://github.com/twinfoundation/node/commit/33940b7e771a0c5af32c18d442deb26a8631fd02))
|
|
9
|
+
|
|
3
10
|
## [0.0.2-next.25](https://github.com/twinfoundation/node/compare/node-core-v0.0.2-next.24...node-core-v0.0.2-next.25) (2025-10-09)
|
|
4
11
|
|
|
5
12
|
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# TWIN Node - Detailed Documentation
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
TWIN Node provides the foundational components for running TWIN nodes, including dynamic extension loading, protocol-based module resolution, and lifecycle management.
|
|
6
|
+
|
|
7
|
+
## Protocol-Based Extension Loading
|
|
8
|
+
|
|
9
|
+
The TWIN Node supports dynamic extension loading from multiple sources:
|
|
10
|
+
|
|
11
|
+
### Local Files
|
|
12
|
+
|
|
13
|
+
Load extensions from your filesystem:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
TWIN_EXTENSIONS="./my-extension.mjs"
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
### NPM Packages
|
|
20
|
+
|
|
21
|
+
Automatically install and load npm packages:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
TWIN_EXTENSIONS="npm:@twin.org/package"
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### HTTPS URLs
|
|
28
|
+
|
|
29
|
+
Download and cache remote extensions:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
TWIN_EXTENSIONS="https://example.com/extension.mjs"
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Extension Lifecycle Hooks
|
|
36
|
+
|
|
37
|
+
Extensions can implement lifecycle hooks to customize node behavior at different stages:
|
|
38
|
+
|
|
39
|
+
- **`extensionInitialise`** - Called before engine initialization
|
|
40
|
+
- **`extensionInitialiseEngine`** - Called during engine initialization
|
|
41
|
+
- **`extensionInitialiseEngineServer`** - Called during server initialization
|
|
42
|
+
- **`extensionShutdown`** - Called during graceful shutdown
|
|
43
|
+
|
|
44
|
+
### Example Extension
|
|
45
|
+
|
|
46
|
+
```javascript
|
|
47
|
+
// my-extension.mjs
|
|
48
|
+
export function extensionInitialise() {
|
|
49
|
+
console.log('Extension initializing...');
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export function extensionInitialiseEngine(engine) {
|
|
53
|
+
console.log('Configuring engine...');
|
|
54
|
+
// Add custom components, routes, etc.
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function extensionInitialiseEngineServer(server) {
|
|
58
|
+
console.log('Configuring server...');
|
|
59
|
+
// Add middleware, routes, etc.
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export function extensionShutdown() {
|
|
63
|
+
console.log('Extension shutting down...');
|
|
64
|
+
// Cleanup resources
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Configuration Options
|
|
69
|
+
|
|
70
|
+
### Cache Management
|
|
71
|
+
|
|
72
|
+
- `TWIN_EXTENSIONS_CACHE_TTL_HOURS` - TTL for HTTPS extensions cache (default: 24)
|
|
73
|
+
- `TWIN_EXTENSIONS_FORCE_REFRESH` - Force refresh all cached extensions (default: false)
|
|
74
|
+
- `TWIN_EXTENSIONS_CACHE_DIRECTORY` - Custom cache directory (default: ".tmp")
|
|
75
|
+
|
|
76
|
+
### Security
|
|
77
|
+
|
|
78
|
+
- `TWIN_EXTENSIONS_MAX_SIZE_MB` - Maximum size for HTTPS downloads (default: 10)
|
|
79
|
+
- `TWIN_EXTENSIONS_CLEAR_CACHE` - Clear cache on startup (default: false)
|
|
80
|
+
|
|
81
|
+
## API Reference
|
|
82
|
+
|
|
83
|
+
### Core Functions
|
|
84
|
+
|
|
85
|
+
#### `overrideModuleImport(executionDirectory, envVars)`
|
|
86
|
+
|
|
87
|
+
Sets up protocol-based module resolution for extensions.
|
|
88
|
+
|
|
89
|
+
#### `buildConfiguration(options)`
|
|
90
|
+
|
|
91
|
+
Builds node configuration from environment variables and options.
|
|
92
|
+
|
|
93
|
+
#### `start(options)`
|
|
94
|
+
|
|
95
|
+
Starts the TWIN node with the specified configuration.
|
|
96
|
+
|
|
97
|
+
### Utility Functions
|
|
98
|
+
|
|
99
|
+
#### `parseModuleProtocol(moduleName)`
|
|
100
|
+
|
|
101
|
+
Parses module name to determine protocol type (npm, https, local, etc.).
|
|
102
|
+
|
|
103
|
+
#### `handleNpmProtocol(packageName, executionDirectory, cacheDirectory)`
|
|
104
|
+
|
|
105
|
+
Handles installation and resolution of npm packages.
|
|
106
|
+
|
|
107
|
+
#### `handleHttpsProtocol(url, executionDirectory, maxSizeMb, cacheDirectory, ttlHours, forceRefresh)`
|
|
108
|
+
|
|
109
|
+
Handles download and caching of HTTPS extensions.
|
|
110
|
+
|
|
111
|
+
## Security Considerations
|
|
112
|
+
|
|
113
|
+
- **HTTPS Only**: Remote extensions must use HTTPS protocol
|
|
114
|
+
- **Size Limits**: Downloads are limited by `TWIN_EXTENSIONS_MAX_SIZE_MB`
|
|
115
|
+
- **Cache TTL**: Extensions are automatically refreshed based on TTL
|
|
116
|
+
- **Security Warnings**: Warnings are displayed when loading remote extensions
|
|
117
|
+
|
|
118
|
+
## Troubleshooting
|
|
119
|
+
|
|
120
|
+
### Common Issues
|
|
121
|
+
|
|
122
|
+
1. **Extension not found**: Check that the path/URL is correct and accessible
|
|
123
|
+
2. **Cache issues**: Use `TWIN_EXTENSIONS_FORCE_REFRESH=true` to force refresh
|
|
124
|
+
3. **Size limit exceeded**: Increase `TWIN_EXTENSIONS_MAX_SIZE_MB` if needed
|
|
125
|
+
4. **Network issues**: Ensure HTTPS URLs are accessible and not blocked by firewall
|
|
126
|
+
|
|
127
|
+
### Debug Mode
|
|
128
|
+
|
|
129
|
+
Set `NODE_ENV=development` for additional debug output during extension loading.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Function: bootstrapContextIdHandlers()
|
|
2
|
+
|
|
3
|
+
> **bootstrapContextIdHandlers**(`engineCore`, `context`, `envVars`, `features`): `Promise`\<`void`\>
|
|
4
|
+
|
|
5
|
+
Bootstrap the context id handlers creating any necessary resources.
|
|
6
|
+
|
|
7
|
+
## Parameters
|
|
8
|
+
|
|
9
|
+
### engineCore
|
|
10
|
+
|
|
11
|
+
`IEngineCore`
|
|
12
|
+
|
|
13
|
+
The engine core for the node.
|
|
14
|
+
|
|
15
|
+
### context
|
|
16
|
+
|
|
17
|
+
`IEngineCoreContext`\<`IEngineServerConfig`, [`INodeEngineState`](../interfaces/INodeEngineState.md)\>
|
|
18
|
+
|
|
19
|
+
The context for the node.
|
|
20
|
+
|
|
21
|
+
### envVars
|
|
22
|
+
|
|
23
|
+
[`INodeEnvironmentVariables`](../interfaces/INodeEnvironmentVariables.md)
|
|
24
|
+
|
|
25
|
+
The environment variables for the node.
|
|
26
|
+
|
|
27
|
+
### features
|
|
28
|
+
|
|
29
|
+
[`NodeFeatures`](../type-aliases/NodeFeatures.md)[]
|
|
30
|
+
|
|
31
|
+
The features that are enabled on the node. The features that are enabled on the node.
|
|
32
|
+
|
|
33
|
+
## Returns
|
|
34
|
+
|
|
35
|
+
`Promise`\<`void`\>
|