awesome-emulator-cli 0.5.1 → 0.6.0
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 +14 -3
- package/dist/cli.js +31 -9
- package/dist/emulator-credentials.d.ts +6 -0
- package/dist/emulator-credentials.js +35 -0
- package/dist/emulator-environment.d.ts +3 -0
- package/dist/emulator-environment.js +6 -0
- package/dist/emulator-options.d.ts +6 -0
- package/dist/emulator-options.js +16 -0
- package/dist/index.d.ts +5 -3
- package/dist/index.js +36 -17
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -33,6 +33,14 @@ Both `AWS_REGION` and `AWS_DEFAULT_REGION` default to `us-east-1`. An explicit r
|
|
|
33
33
|
|
|
34
34
|
The CLI removes inherited AWS credentials, profiles, and service endpoints from the child environment. Credentials or endpoints explicitly set in project or build configuration still need to target the emulator. Commands run without a shell by default; on Windows, `.cmd` and `.bat` commands need `--shell`, which should only be used with trusted arguments.
|
|
35
35
|
|
|
36
|
+
Credentials are read from the emulator's shared credentials file by default. If an SDK or application needs standard AWS credential environment variables, opt in for a wrapped command with `--credentials env`:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npx awesome-emulator run --credentials env -- npm test
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
This passes only credentials generated by the emulator as `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and, when present, `AWS_SESSION_TOKEN`. See the [SDK configuration guide](./docs/sdk-configuration.md) for the CA and truststore paths exposed to child commands.
|
|
43
|
+
|
|
36
44
|
The CLI can run commands from projects without a `package.json` too. For example, run Python tests with:
|
|
37
45
|
|
|
38
46
|
```sh
|
|
@@ -43,17 +51,20 @@ The same pattern works with AWS CLI, Go, Java, Rust, and .NET projects. Use `--s
|
|
|
43
51
|
|
|
44
52
|
## Reuse the emulator across commands
|
|
45
53
|
|
|
46
|
-
Use a named session when setup and tests run as separate commands or CI steps
|
|
54
|
+
Use a named session when setup and tests run as separate commands or CI steps. Set `AWS_EMULATOR_STATE_DIR` to keep emulator files outside `~/.aws/emulator` without changing `HOME`; the same value is used by `up`, `exec`, and `down`:
|
|
47
55
|
|
|
48
56
|
```sh
|
|
57
|
+
export AWS_EMULATOR_STATE_DIR="${RUNNER_TEMP:-/tmp}/awesome-emulator-cli"
|
|
49
58
|
npx awesome-emulator up --session ci-tests --init -- node scripts/seed-emulator.js
|
|
50
59
|
npx awesome-emulator exec --session ci-tests -- npm test
|
|
51
60
|
npx awesome-emulator down --session ci-tests
|
|
52
61
|
```
|
|
53
62
|
|
|
63
|
+
Use `--state-dir <path>` to override the environment variable for one command. Relative paths are resolved from the current working directory. The Node.js API accepts the same setting as `stateDirectory`.
|
|
64
|
+
|
|
54
65
|
`--init` runs once after the emulator is healthy. If it fails, `up` stops the container and exits with an error. Initializer output goes to stderr so `up`'s JSON output stays machine-readable. Use `down` in an always-run CI cleanup step to stop the session after failures.
|
|
55
66
|
|
|
56
|
-
Session metadata is stored
|
|
67
|
+
Session metadata is stored in `<state-dir>/sessions/` and contains connection details, not credential values. The default directory is `~/.aws/emulator/` (Windows: `%USERPROFILE%\.aws\emulator\`).
|
|
57
68
|
|
|
58
69
|
## Use from Node.js
|
|
59
70
|
|
|
@@ -74,7 +85,7 @@ Pass an `AbortSignal` as `signal` to cancel image building or startup. For an al
|
|
|
74
85
|
|
|
75
86
|
## Local files and telemetry
|
|
76
87
|
|
|
77
|
-
The emulator stores its config, credentials, and CA certificate under
|
|
88
|
+
The emulator stores its config, credentials, and CA certificate under `<state-dir>/<port>/`. Resources stay in memory and are removed when the container stops.
|
|
78
89
|
|
|
79
90
|
Telemetry is on by default. Turn it off for a run with `--telemetry off`. See [AWS Emulator telemetry details](https://docs.aws.amazon.com/emulator/latest/userguide/telemetry.html) for what it collects.
|
|
80
91
|
|
package/dist/cli.js
CHANGED
|
@@ -6,21 +6,23 @@ import { DEFAULT_AWS_REGION, SUPPORTED_EMULATOR_SDKS } from "./emulator-environm
|
|
|
6
6
|
function usage() {
|
|
7
7
|
console.log(`Usage:
|
|
8
8
|
awesome-emulator prepare [--version <version>]
|
|
9
|
-
awesome-emulator start [options]
|
|
10
|
-
awesome-emulator run [options] [--region <region>] [--sdk <family>]... [--shell] -- <command> [args...]
|
|
11
|
-
awesome-emulator up --session <name> [options] [--init [child options] -- <command> [args...]]
|
|
12
|
-
awesome-emulator exec --session <name> [--region <region>] [--sdk <family>]... [--shell] -- <command> [args...]
|
|
13
|
-
awesome-emulator down --session <name>
|
|
9
|
+
awesome-emulator start [options] [--state-dir <path>]
|
|
10
|
+
awesome-emulator run [options] [--state-dir <path>] [--region <region>] [--sdk <family>]... [--credentials <files|env>] [--shell] -- <command> [args...]
|
|
11
|
+
awesome-emulator up --session <name> [options] [--state-dir <path>] [--init [child options] -- <command> [args...]]
|
|
12
|
+
awesome-emulator exec --session <name> [--state-dir <path>] [--region <region>] [--sdk <family>]... [--credentials <files|env>] [--shell] -- <command> [args...]
|
|
13
|
+
awesome-emulator down --session <name> [--state-dir <path>]
|
|
14
14
|
|
|
15
15
|
Options:
|
|
16
16
|
-v, --version <version> AWS Emulator version (default: ${DEFAULT_VERSION})
|
|
17
17
|
-p, --port <port> (start/run/up) Host port; 0 chooses an available port (default: 9297)
|
|
18
18
|
-t, --telemetry <on|off> (start/run/up) Telemetry setting (default: on)
|
|
19
19
|
--memory <limit> (start/run/up) Container memory limit (default: 2g)
|
|
20
|
+
--state-dir <path> (start/run/up/exec/down) Emulator state directory (default: AWS_EMULATOR_STATE_DIR or ~/.aws/emulator)
|
|
20
21
|
--region <region> (run/exec/up --init) Default region for the child command (default: ${DEFAULT_AWS_REGION})
|
|
21
22
|
--session <name> (up/exec/down) Persistent emulator session name
|
|
22
23
|
--sdk <family> (run/exec/up --init) Add SDK-specific TLS settings; repeatable
|
|
23
24
|
(${SUPPORTED_EMULATOR_SDKS.join(", ")})
|
|
25
|
+
--credentials <mode> (run/exec/up --init) Credentials delivery: files (default) or env
|
|
24
26
|
--shell (run/exec/up --init) Enable .cmd/.bat and built-ins; trusted values only
|
|
25
27
|
--init (up only) Run a command after the emulator becomes healthy
|
|
26
28
|
-h, --help Show this help`);
|
|
@@ -83,6 +85,8 @@ function parse(argv) {
|
|
|
83
85
|
"--memory": "memory",
|
|
84
86
|
"--region": "region",
|
|
85
87
|
"--session": "session",
|
|
88
|
+
"--state-dir": "stateDirectory",
|
|
89
|
+
"--credentials": "credentials",
|
|
86
90
|
};
|
|
87
91
|
const key = optionNames[token];
|
|
88
92
|
if (!key)
|
|
@@ -93,16 +97,29 @@ function parse(argv) {
|
|
|
93
97
|
if (key === "session" && command !== "up" && command !== "exec" && command !== "down") {
|
|
94
98
|
throw new Error("--session can only be used with the up, exec, or down command.");
|
|
95
99
|
}
|
|
100
|
+
if (key === "stateDirectory" && !["start", "run", "up", "exec", "down"].includes(command ?? "")) {
|
|
101
|
+
throw new Error("--state-dir can only be used with start, run, up, exec, or down.");
|
|
102
|
+
}
|
|
103
|
+
if (key === "credentials" && command !== "run" && command !== "exec" && command !== "up") {
|
|
104
|
+
throw new Error("--credentials can only be used with the run or exec command, or with up --init.");
|
|
105
|
+
}
|
|
96
106
|
if (command === "prepare" && key !== "version") {
|
|
97
107
|
throw new Error(`${token} can only be used with the start or run command.`);
|
|
98
108
|
}
|
|
99
|
-
if ((command === "exec" || command === "down") && key !== "region" && key !== "session") {
|
|
109
|
+
if ((command === "exec" || command === "down") && key !== "region" && key !== "session" && key !== "stateDirectory" && key !== "credentials") {
|
|
100
110
|
throw new Error(`${token} cannot be used with the ${command} command.`);
|
|
101
111
|
}
|
|
102
112
|
const value = argv[index + 1];
|
|
103
113
|
if (!value || value.startsWith("--"))
|
|
104
114
|
throw new Error(`Missing value for ${token}`);
|
|
105
|
-
|
|
115
|
+
if (key === "credentials") {
|
|
116
|
+
if (value !== "files" && value !== "env")
|
|
117
|
+
throw new Error("--credentials must be files or env.");
|
|
118
|
+
options.credentials = value === "env" ? "environment" : "files";
|
|
119
|
+
}
|
|
120
|
+
else {
|
|
121
|
+
options[key] = value;
|
|
122
|
+
}
|
|
106
123
|
index += 1;
|
|
107
124
|
}
|
|
108
125
|
if ((command === "up" || command === "exec" || command === "down") && !options.session) {
|
|
@@ -112,7 +129,7 @@ function parse(argv) {
|
|
|
112
129
|
if (initRequested && (!separator || commandArgs.length === 0)) {
|
|
113
130
|
throw new Error("Usage: awesome-emulator up --session <name> [options] --init -- <command> [args...]");
|
|
114
131
|
}
|
|
115
|
-
if (!initRequested && (separator || options.region || options.sdks || options.shell)) {
|
|
132
|
+
if (!initRequested && (separator || options.region || options.sdks || options.shell || options.credentials)) {
|
|
116
133
|
throw new Error("Child command options and arguments for up require --init.");
|
|
117
134
|
}
|
|
118
135
|
}
|
|
@@ -152,6 +169,7 @@ async function main(signal) {
|
|
|
152
169
|
port: parsed.options.port,
|
|
153
170
|
telemetry: parsed.options.telemetry,
|
|
154
171
|
memory: parsed.options.memory,
|
|
172
|
+
stateDirectory: parsed.options.stateDirectory,
|
|
155
173
|
signal,
|
|
156
174
|
init: parsed.options.init ? {
|
|
157
175
|
command: initCommand,
|
|
@@ -159,6 +177,7 @@ async function main(signal) {
|
|
|
159
177
|
region: parsed.options.region,
|
|
160
178
|
sdks: parsed.options.sdks,
|
|
161
179
|
shell: parsed.options.shell,
|
|
180
|
+
credentials: parsed.options.credentials,
|
|
162
181
|
} : undefined,
|
|
163
182
|
});
|
|
164
183
|
console.log(JSON.stringify(session, null, 2));
|
|
@@ -172,13 +191,15 @@ async function main(signal) {
|
|
|
172
191
|
region: parsed.options.region,
|
|
173
192
|
sdks: parsed.options.sdks,
|
|
174
193
|
shell: parsed.options.shell,
|
|
194
|
+
stateDirectory: parsed.options.stateDirectory,
|
|
195
|
+
credentials: parsed.options.credentials,
|
|
175
196
|
signal,
|
|
176
197
|
});
|
|
177
198
|
}
|
|
178
199
|
if (parsed.command === "down") {
|
|
179
200
|
if (parsed.commandArgs.length > 0)
|
|
180
201
|
throw new Error("The down command does not accept child command arguments.");
|
|
181
|
-
await downEmulatorSession(parsed.options.session);
|
|
202
|
+
await downEmulatorSession(parsed.options.session, { stateDirectory: parsed.options.stateDirectory });
|
|
182
203
|
console.log(`Emulator session "${parsed.options.session}" stopped.`);
|
|
183
204
|
return 0;
|
|
184
205
|
}
|
|
@@ -193,6 +214,7 @@ async function main(signal) {
|
|
|
193
214
|
port: parsed.options.port,
|
|
194
215
|
telemetry: parsed.options.telemetry,
|
|
195
216
|
memory: parsed.options.memory,
|
|
217
|
+
stateDirectory: parsed.options.stateDirectory,
|
|
196
218
|
signal,
|
|
197
219
|
});
|
|
198
220
|
try {
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { readFile } from "node:fs/promises";
|
|
2
|
+
export async function readEmulatorCredentialEnvironment(credentialsFile) {
|
|
3
|
+
const contents = await readFile(credentialsFile, "utf8");
|
|
4
|
+
const credentials = {};
|
|
5
|
+
let inDefaultProfile = false;
|
|
6
|
+
for (const rawLine of contents.replace(/^\uFEFF/, "").split(/\r?\n/)) {
|
|
7
|
+
const line = rawLine.trim();
|
|
8
|
+
if (line.length === 0 || line.startsWith("#") || line.startsWith(";"))
|
|
9
|
+
continue;
|
|
10
|
+
const section = /^\[([^\]]+)\]$/.exec(line);
|
|
11
|
+
if (section) {
|
|
12
|
+
inDefaultProfile = section[1].trim().toLowerCase() === "default";
|
|
13
|
+
continue;
|
|
14
|
+
}
|
|
15
|
+
if (!inDefaultProfile)
|
|
16
|
+
continue;
|
|
17
|
+
const entry = /^([^=]+?)\s*=\s*(.*)$/.exec(line);
|
|
18
|
+
if (!entry)
|
|
19
|
+
continue;
|
|
20
|
+
const key = entry[1].trim().toLowerCase();
|
|
21
|
+
if (["aws_access_key_id", "aws_secret_access_key", "aws_session_token"].includes(key)) {
|
|
22
|
+
credentials[key] = entry[2].trim();
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
const accessKeyId = credentials.aws_access_key_id;
|
|
26
|
+
const secretAccessKey = credentials.aws_secret_access_key;
|
|
27
|
+
if (!accessKeyId || !secretAccessKey) {
|
|
28
|
+
throw new Error("The Emulator credentials file does not contain a usable [default] access key and secret key.");
|
|
29
|
+
}
|
|
30
|
+
return {
|
|
31
|
+
AWS_ACCESS_KEY_ID: accessKeyId,
|
|
32
|
+
AWS_SECRET_ACCESS_KEY: secretAccessKey,
|
|
33
|
+
...(credentials.aws_session_token ? { AWS_SESSION_TOKEN: credentials.aws_session_token } : {}),
|
|
34
|
+
};
|
|
35
|
+
}
|
|
@@ -37,6 +37,8 @@ const JAVA_OPTION_ENVIRONMENT_KEYS = [
|
|
|
37
37
|
"ANT_OPTS",
|
|
38
38
|
"SBT_OPTS",
|
|
39
39
|
];
|
|
40
|
+
// npm exec --package exports its selector to children; nested npx must use its own requested package.
|
|
41
|
+
const NPM_LAUNCHER_ENVIRONMENT_KEYS = ["npm_config_package"];
|
|
40
42
|
const JVM_WIDE_JAVA_OPTION_ENVIRONMENT_KEYS = [
|
|
41
43
|
"JAVA_TOOL_OPTIONS",
|
|
42
44
|
"JDK_JAVA_OPTIONS",
|
|
@@ -59,6 +61,9 @@ export function createEmulatorConnectionSettings(port, stateDirectory) {
|
|
|
59
61
|
const endpointUrl = `https://127.0.0.1:${port}`;
|
|
60
62
|
const portDirectory = path.join(stateDirectory, String(port));
|
|
61
63
|
const environment = {
|
|
64
|
+
AWS_EMULATOR_STATE_DIR: stateDirectory,
|
|
65
|
+
AWS_EMULATOR_CA_FILE: path.join(portDirectory, "ca.pem"),
|
|
66
|
+
AWS_EMULATOR_TRUSTSTORE_FILE: path.join(portDirectory, "truststore.p12"),
|
|
62
67
|
AWS_ENDPOINT_URL: endpointUrl,
|
|
63
68
|
AWS_SHARED_CREDENTIALS_FILE: path.join(portDirectory, "emulator_credentials"),
|
|
64
69
|
AWS_CONFIG_FILE: path.join(portDirectory, "config"),
|
|
@@ -86,6 +91,7 @@ export function createChildEnvironment(parentEnvironment, emulatorEnvironment, o
|
|
|
86
91
|
const controlledEnvironmentKeys = new Set([
|
|
87
92
|
...Object.keys(emulatorEnvironment),
|
|
88
93
|
...AWS_CREDENTIAL_ENVIRONMENT_KEYS,
|
|
94
|
+
...NPM_LAUNCHER_ENVIRONMENT_KEYS,
|
|
89
95
|
...(sdks.includes("rust") || sdks.includes("dotnet") ? ["SSL_CERT_FILE"] : []),
|
|
90
96
|
].map(normalizeName));
|
|
91
97
|
for (const key of Object.keys(childEnvironment)) {
|
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import type { EmulatorSdk } from "./emulator-environment.js";
|
|
2
|
+
export type EmulatorCredentialsMode = "files" | "environment";
|
|
3
|
+
export declare function resolveEmulatorCredentialsMode(value: string | undefined): EmulatorCredentialsMode;
|
|
2
4
|
export type StartEmulatorOptions = {
|
|
3
5
|
version?: string;
|
|
6
|
+
stateDirectory?: string;
|
|
4
7
|
port?: number | string;
|
|
5
8
|
telemetry?: string;
|
|
6
9
|
memory?: string;
|
|
@@ -18,6 +21,8 @@ export type RunWithEmulatorOptions = StartEmulatorOptions & {
|
|
|
18
21
|
region?: string;
|
|
19
22
|
/** Add SDK-specific TLS settings for the selected SDK families. */
|
|
20
23
|
sdks?: EmulatorSdk[];
|
|
24
|
+
/** Pass Emulator-generated credentials through AWS credential environment variables instead of relying only on files. */
|
|
25
|
+
credentials?: EmulatorCredentialsMode;
|
|
21
26
|
};
|
|
22
27
|
export type PrepareEmulatorOptions = Pick<StartEmulatorOptions, "version" | "signal">;
|
|
23
28
|
export type ResolvedEmulatorOptions = {
|
|
@@ -27,6 +32,7 @@ export type ResolvedEmulatorOptions = {
|
|
|
27
32
|
memory: string;
|
|
28
33
|
startupTimeoutMs: number;
|
|
29
34
|
};
|
|
35
|
+
export declare function resolveEmulatorStateDirectory(value: string | undefined, environment?: NodeJS.ProcessEnv, homeDirectory?: string, workingDirectory?: string): string;
|
|
30
36
|
export declare const DEFAULT_VERSION = "1.0.533";
|
|
31
37
|
export declare function resolveEmulatorVersion(value: string | undefined, environment?: NodeJS.ProcessEnv): string;
|
|
32
38
|
export declare function resolveEmulatorOptions(options: StartEmulatorOptions, environment?: NodeJS.ProcessEnv): ResolvedEmulatorOptions;
|
package/dist/emulator-options.js
CHANGED
|
@@ -1,3 +1,19 @@
|
|
|
1
|
+
import os from "node:os";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
export function resolveEmulatorCredentialsMode(value) {
|
|
4
|
+
const mode = value ?? "files";
|
|
5
|
+
if (mode !== "files" && mode !== "environment") {
|
|
6
|
+
throw new Error("Credentials mode must be files or environment.");
|
|
7
|
+
}
|
|
8
|
+
return mode;
|
|
9
|
+
}
|
|
10
|
+
export function resolveEmulatorStateDirectory(value, environment = process.env, homeDirectory = os.homedir(), workingDirectory = process.cwd()) {
|
|
11
|
+
const configuredDirectory = value ?? environment.AWS_EMULATOR_STATE_DIR;
|
|
12
|
+
if (configuredDirectory !== undefined && configuredDirectory.trim().length === 0) {
|
|
13
|
+
throw new Error("Emulator state directory must not be empty.");
|
|
14
|
+
}
|
|
15
|
+
return path.resolve(workingDirectory, configuredDirectory ?? path.join(homeDirectory, ".aws", "emulator"));
|
|
16
|
+
}
|
|
1
17
|
export const DEFAULT_VERSION = "1.0.533";
|
|
2
18
|
const DEFAULT_PORT = 9297;
|
|
3
19
|
const DEFAULT_MEMORY = "2g";
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { type EmulatorEnvironment, type EmulatorSdk } from "./emulator-environment.js";
|
|
2
|
-
import { type PrepareEmulatorOptions, type RunWithEmulatorOptions, type StartEmulatorOptions } from "./emulator-options.js";
|
|
2
|
+
import { type PrepareEmulatorOptions, type EmulatorCredentialsMode, type RunWithEmulatorOptions, type StartEmulatorOptions } from "./emulator-options.js";
|
|
3
3
|
export type { PrepareEmulatorOptions, RunWithEmulatorOptions, StartEmulatorOptions } from "./emulator-options.js";
|
|
4
|
+
export type { EmulatorCredentialsMode } from "./emulator-options.js";
|
|
4
5
|
export type { EmulatorEnvironment, EmulatorSdk } from "./emulator-environment.js";
|
|
5
6
|
export type EmulatorSession = {
|
|
6
7
|
version: string;
|
|
@@ -17,13 +18,14 @@ export type EmulatorSession = {
|
|
|
17
18
|
export type PersistentEmulatorSession = Omit<EmulatorSession, "containerId" | "stop"> & {
|
|
18
19
|
name: string;
|
|
19
20
|
};
|
|
20
|
-
export type EmulatorSessionExecOptions = Pick<RunWithEmulatorOptions, "shell" | "sdks" | "region" | "signal">;
|
|
21
|
+
export type EmulatorSessionExecOptions = Pick<RunWithEmulatorOptions, "shell" | "sdks" | "region" | "signal" | "stateDirectory" | "credentials">;
|
|
21
22
|
export type EmulatorSessionInitCommand = {
|
|
22
23
|
command: string;
|
|
23
24
|
args?: string[];
|
|
24
25
|
shell?: boolean;
|
|
25
26
|
sdks?: EmulatorSdk[];
|
|
26
27
|
region?: string;
|
|
28
|
+
credentials?: EmulatorCredentialsMode;
|
|
27
29
|
};
|
|
28
30
|
export type UpEmulatorSessionOptions = StartEmulatorOptions & {
|
|
29
31
|
init?: EmulatorSessionInitCommand;
|
|
@@ -33,7 +35,7 @@ export declare function prepareEmulatorImage(options?: PrepareEmulatorOptions):
|
|
|
33
35
|
export declare function startEmulator(options?: StartEmulatorOptions): Promise<EmulatorSession>;
|
|
34
36
|
export declare function upEmulatorSession(name: string, options?: UpEmulatorSessionOptions): Promise<PersistentEmulatorSession>;
|
|
35
37
|
export declare function execEmulatorSession(name: string, command: string, args?: string[], options?: EmulatorSessionExecOptions): Promise<number>;
|
|
36
|
-
export declare function downEmulatorSession(name: string): Promise<void>;
|
|
38
|
+
export declare function downEmulatorSession(name: string, options?: Pick<StartEmulatorOptions, "stateDirectory">): Promise<void>;
|
|
37
39
|
/**
|
|
38
40
|
* Run a child process with AWS Emulator settings and stop the emulator afterward.
|
|
39
41
|
*/
|
package/dist/index.js
CHANGED
|
@@ -2,20 +2,26 @@ import { randomBytes } from "node:crypto";
|
|
|
2
2
|
import { mkdir, readFile } from "node:fs/promises";
|
|
3
3
|
import https from "node:https";
|
|
4
4
|
import net from "node:net";
|
|
5
|
-
import os from "node:os";
|
|
6
5
|
import path from "node:path";
|
|
7
6
|
import { createRetryableStop, startContainer, stopContainer, withEmulator } from "./container-lifecycle.js";
|
|
8
7
|
import { docker, throwIfAborted } from "./docker.js";
|
|
9
8
|
import { createChildEnvironment, createEmulatorConnectionSettings, normalizeEmulatorSdks, resolveAwsRegion, } from "./emulator-environment.js";
|
|
9
|
+
import { readEmulatorCredentialEnvironment } from "./emulator-credentials.js";
|
|
10
10
|
import { ensureEmulatorImage, getArchitecture } from "./emulator-image.js";
|
|
11
11
|
import { isSessionOwnerRunning, readSession, removeSession, reserveSession, validateSessionName, writeRunningSession } from "./session-store.js";
|
|
12
|
-
import { resolveEmulatorOptions, resolveEmulatorVersion, } from "./emulator-options.js";
|
|
12
|
+
import { resolveEmulatorOptions, resolveEmulatorStateDirectory, resolveEmulatorCredentialsMode, resolveEmulatorVersion, } from "./emulator-options.js";
|
|
13
13
|
import { runCommand } from "./process.js";
|
|
14
|
+
async function createCommandEnvironment(parentEnvironment, emulatorEnvironment, options = {}) {
|
|
15
|
+
const { credentials, ...environmentOptions } = options;
|
|
16
|
+
const credentialsMode = resolveEmulatorCredentialsMode(credentials);
|
|
17
|
+
const childEnvironment = createChildEnvironment(parentEnvironment, emulatorEnvironment, environmentOptions);
|
|
18
|
+
if (credentialsMode === "environment") {
|
|
19
|
+
Object.assign(childEnvironment, await readEmulatorCredentialEnvironment(emulatorEnvironment.AWS_SHARED_CREDENTIALS_FILE));
|
|
20
|
+
}
|
|
21
|
+
return childEnvironment;
|
|
22
|
+
}
|
|
14
23
|
const MANAGED_CONTAINER_LABEL = "io.github.c19yamamoto.awesome-emulator-cli.managed";
|
|
15
24
|
const SESSION_CONTAINER_LABEL = "io.github.c19yamamoto.awesome-emulator-cli.session";
|
|
16
|
-
function emulatorStateDirectory() {
|
|
17
|
-
return path.join(os.homedir(), ".aws", "emulator");
|
|
18
|
-
}
|
|
19
25
|
/** Build or reuse the selected AWS Emulator Docker image without starting a container. */
|
|
20
26
|
export async function prepareEmulatorImage(options = {}) {
|
|
21
27
|
throwIfAborted(options.signal);
|
|
@@ -116,13 +122,12 @@ async function waitUntilHealthy(containerId, port, stateDirectory, timeoutMs, si
|
|
|
116
122
|
* The returned object includes SDK environment variables and an idempotent
|
|
117
123
|
* stop() function. Port 0 asks the wrapper to choose an available local port.
|
|
118
124
|
*/
|
|
119
|
-
async function startEmulatorWithIdentity(options, containerName, labels) {
|
|
125
|
+
async function startEmulatorWithIdentity(options, containerName, labels, stateDirectory = resolveEmulatorStateDirectory(options.stateDirectory)) {
|
|
120
126
|
throwIfAborted(options.signal);
|
|
121
127
|
const { version, requestedPort, telemetry, memory, startupTimeoutMs } = resolveEmulatorOptions(options);
|
|
122
128
|
const port = requestedPort === 0 ? await getAvailablePort() : requestedPort;
|
|
123
129
|
throwIfAborted(options.signal);
|
|
124
130
|
const architecture = getArchitecture();
|
|
125
|
-
const stateDirectory = emulatorStateDirectory();
|
|
126
131
|
await mkdir(stateDirectory, { recursive: true, mode: 0o700 });
|
|
127
132
|
const image = await ensureEmulatorImage(version, architecture, options.signal);
|
|
128
133
|
throwIfAborted(options.signal);
|
|
@@ -167,11 +172,15 @@ export async function upEmulatorSession(name, options = {}) {
|
|
|
167
172
|
validateSessionName(name);
|
|
168
173
|
const { init, ...emulatorOptions } = options;
|
|
169
174
|
const initOptions = init
|
|
170
|
-
? {
|
|
175
|
+
? {
|
|
176
|
+
sdks: normalizeEmulatorSdks(init.sdks),
|
|
177
|
+
region: resolveAwsRegion(init.region),
|
|
178
|
+
credentials: resolveEmulatorCredentialsMode(init.credentials),
|
|
179
|
+
}
|
|
171
180
|
: undefined;
|
|
172
181
|
if (init && !init.command)
|
|
173
182
|
throw new Error("An initialization command is required.");
|
|
174
|
-
const stateDirectory =
|
|
183
|
+
const stateDirectory = resolveEmulatorStateDirectory(emulatorOptions.stateDirectory);
|
|
175
184
|
const containerName = `awesome-emulator-cli-session-${randomBytes(4).toString("hex")}-${name}`;
|
|
176
185
|
await reserveSession(stateDirectory, name, containerName);
|
|
177
186
|
let emulator;
|
|
@@ -179,9 +188,9 @@ export async function upEmulatorSession(name, options = {}) {
|
|
|
179
188
|
emulator = await startEmulatorWithIdentity(emulatorOptions, containerName, {
|
|
180
189
|
[MANAGED_CONTAINER_LABEL]: "true",
|
|
181
190
|
[SESSION_CONTAINER_LABEL]: name,
|
|
182
|
-
});
|
|
191
|
+
}, stateDirectory);
|
|
183
192
|
if (init && initOptions) {
|
|
184
|
-
const childEnvironment =
|
|
193
|
+
const childEnvironment = await createCommandEnvironment(process.env, emulator.environment, initOptions);
|
|
185
194
|
const exitCode = await runCommand(init.command, init.args ?? [], childEnvironment, options.signal, init.shell ?? false, "stderr");
|
|
186
195
|
if (exitCode !== 0) {
|
|
187
196
|
throwIfAborted(options.signal);
|
|
@@ -254,10 +263,11 @@ export async function execEmulatorSession(name, command, args = [], options = {}
|
|
|
254
263
|
if (!command)
|
|
255
264
|
throw new Error("A command is required.");
|
|
256
265
|
validateSessionName(name);
|
|
257
|
-
const { signal, shell = false, sdks: requestedSdks = [], region } = options;
|
|
266
|
+
const { signal, shell = false, sdks: requestedSdks = [], region, stateDirectory: requestedStateDirectory } = options;
|
|
267
|
+
const credentials = resolveEmulatorCredentialsMode(options.credentials);
|
|
258
268
|
const childRegion = resolveAwsRegion(region);
|
|
259
269
|
const sdks = normalizeEmulatorSdks(requestedSdks);
|
|
260
|
-
const stateDirectory =
|
|
270
|
+
const stateDirectory = resolveEmulatorStateDirectory(requestedStateDirectory);
|
|
261
271
|
const session = await readSession(stateDirectory, name);
|
|
262
272
|
if (session.state !== "running") {
|
|
263
273
|
throw new Error(`Emulator session "${name}" is still starting. Wait for "awesome-emulator up" to finish before running commands.`);
|
|
@@ -273,12 +283,16 @@ export async function execEmulatorSession(name, command, args = [], options = {}
|
|
|
273
283
|
throw new Error(`Emulator session "${name}" is not running. Run "awesome-emulator down --session ${name}" to remove it.`);
|
|
274
284
|
}
|
|
275
285
|
const emulator = createEmulatorConnectionSettings(session.port, stateDirectory);
|
|
276
|
-
const childEnvironment =
|
|
286
|
+
const childEnvironment = await createCommandEnvironment(process.env, emulator.environment, {
|
|
287
|
+
sdks,
|
|
288
|
+
region: childRegion,
|
|
289
|
+
credentials,
|
|
290
|
+
});
|
|
277
291
|
return runCommand(command, args, childEnvironment, signal, shell);
|
|
278
292
|
}
|
|
279
|
-
export async function downEmulatorSession(name) {
|
|
293
|
+
export async function downEmulatorSession(name, options = {}) {
|
|
280
294
|
validateSessionName(name);
|
|
281
|
-
const stateDirectory =
|
|
295
|
+
const stateDirectory = resolveEmulatorStateDirectory(options.stateDirectory);
|
|
282
296
|
const session = await readSession(stateDirectory, name);
|
|
283
297
|
if (session.state === "starting" && isSessionOwnerRunning(session)) {
|
|
284
298
|
throw new Error(`Emulator session "${name}" is still starting. Retry after "awesome-emulator up" finishes.`);
|
|
@@ -295,10 +309,15 @@ export async function runWithEmulator(command, args = [], options = {}) {
|
|
|
295
309
|
if (!command)
|
|
296
310
|
throw new Error("A command is required.");
|
|
297
311
|
const { shell = false, sdks: requestedSdks = [], region, ...emulatorOptions } = options;
|
|
312
|
+
const credentials = resolveEmulatorCredentialsMode(options.credentials);
|
|
298
313
|
const childRegion = resolveAwsRegion(region);
|
|
299
314
|
const sdks = normalizeEmulatorSdks(requestedSdks);
|
|
300
315
|
return withEmulator(() => startEmulator(emulatorOptions), async (emulator) => {
|
|
301
|
-
const childEnvironment =
|
|
316
|
+
const childEnvironment = await createCommandEnvironment(process.env, emulator.environment, {
|
|
317
|
+
sdks,
|
|
318
|
+
region: childRegion,
|
|
319
|
+
credentials,
|
|
320
|
+
});
|
|
302
321
|
return runCommand(command, args, childEnvironment, emulatorOptions.signal, shell);
|
|
303
322
|
});
|
|
304
323
|
}
|