@metreeca/gear-gcp 0.3.0 → 0.4.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/dist/index.d.ts CHANGED
@@ -1,10 +1,37 @@
1
1
  /**
2
- * Google Cloud service implementations.
2
+ * The Google Cloud Platform execution environment.
3
3
  *
4
- * Provides implementations of the shared services a job relies on, backed by Google Cloud facilities, to be bound in
5
- * place of the defaults for the duration of an execution.
4
+ * Exposes the ambient settings shared by the Google Cloud integrations, such as whether the process is deployed to a
5
+ * Google Cloud runtime, which port its HTTP service listens on and which project it runs in. Each setting is resolved
6
+ * on first access and retained afterwards, so later changes to the environment of the process are not reflected.
6
7
  *
7
- * @module index
8
+ * @see {@link https://cloud.google.com/docs/authentication Google Cloud Authentication}
8
9
  */
9
- export {};
10
+ export declare const gcp: {
11
+ /**
12
+ * Whether the current process is running on Google Cloud.
13
+ *
14
+ * The flag is set for a process deployed to Cloud Run, Cloud Functions, App Engine, Google Kubernetes Engine or
15
+ * Compute Engine. It is cleared for a process running locally, such as a development server or a test runner.
16
+ *
17
+ * @see {@link https://cloud.google.com/run/docs/container-contract#env-vars Cloud Run environment variables}
18
+ * @see {@link https://cloud.google.com/appengine/docs/standard/nodejs/runtime#environment_variables App Engine environment variables}
19
+ */
20
+ readonly cloud: boolean;
21
+ /**
22
+ * The port an HTTP service is expected to listen on.
23
+ *
24
+ * The port is read from the `PORT` environment variable, which managed Google Cloud runtimes set to the port they
25
+ * route requests to; it defaults to `8080` if the variable is unset or empty.
26
+ */
27
+ readonly port: number;
28
+ /**
29
+ * The ID of the Google Cloud project the process runs in.
30
+ *
31
+ * On a Google Cloud runtime the project is the one the process is deployed to; locally it is the one selected by
32
+ * the application default credentials or by the `gcloud` configuration. The promise rejects if no project is
33
+ * configured for the process.
34
+ */
35
+ readonly project: Promise<string>;
36
+ };
10
37
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuCA;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG;IAEf;;;;;;;;OAQG;oBACU,OAAO;IAMpB;;;;;OAKG;mBACS,MAAM;IAMlB;;;;;;OAMG;sBACY,OAAO,CAAC,MAAM,CAAC;CAM7B,CAAC"}
package/dist/index.js CHANGED
@@ -13,5 +13,63 @@
13
13
  * See the License for the specific language governing permissions and
14
14
  * limitations under the License.
15
15
  */
16
- export {};
16
+ /**
17
+ * Google Cloud service implementations.
18
+ *
19
+ * Exposes the settings of the Google Cloud environment a job runs in. Dedicated subpath modules provide implementations
20
+ * of the shared services a job relies on, backed by Google Cloud facilities, to be bound in place of the defaults for
21
+ * the duration of an execution, with no configuration beyond the ambient Google Cloud credentials.
22
+ *
23
+ * @module index
24
+ */
25
+ import { immutable } from "@metreeca/core/values";
26
+ import { getGCPResidency } from "gcp-metadata";
27
+ import { GoogleAuth } from "google-auth-library";
28
+ /**
29
+ * Values of the {@link gcp} settings, each resolved on first access and kept for the lifetime of the process.
30
+ */
31
+ const cache = {};
32
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
33
+ /**
34
+ * The Google Cloud Platform execution environment.
35
+ *
36
+ * Exposes the ambient settings shared by the Google Cloud integrations, such as whether the process is deployed to a
37
+ * Google Cloud runtime, which port its HTTP service listens on and which project it runs in. Each setting is resolved
38
+ * on first access and retained afterwards, so later changes to the environment of the process are not reflected.
39
+ *
40
+ * @see {@link https://cloud.google.com/docs/authentication Google Cloud Authentication}
41
+ */
42
+ export const gcp = immutable({
43
+ /**
44
+ * Whether the current process is running on Google Cloud.
45
+ *
46
+ * The flag is set for a process deployed to Cloud Run, Cloud Functions, App Engine, Google Kubernetes Engine or
47
+ * Compute Engine. It is cleared for a process running locally, such as a development server or a test runner.
48
+ *
49
+ * @see {@link https://cloud.google.com/run/docs/container-contract#env-vars Cloud Run environment variables}
50
+ * @see {@link https://cloud.google.com/appengine/docs/standard/nodejs/runtime#environment_variables App Engine environment variables}
51
+ */
52
+ get cloud() {
53
+ return cache.cloud ??= getGCPResidency() || Boolean(process.env.GAE_SERVICE);
54
+ },
55
+ /**
56
+ * The port an HTTP service is expected to listen on.
57
+ *
58
+ * The port is read from the `PORT` environment variable, which managed Google Cloud runtimes set to the port they
59
+ * route requests to; it defaults to `8080` if the variable is unset or empty.
60
+ */
61
+ get port() {
62
+ return cache.port ??= Number(process.env.PORT || 8080);
63
+ },
64
+ /**
65
+ * The ID of the Google Cloud project the process runs in.
66
+ *
67
+ * On a Google Cloud runtime the project is the one the process is deployed to; locally it is the one selected by
68
+ * the application default credentials or by the `gcloud` configuration. The promise rejects if no project is
69
+ * configured for the process.
70
+ */
71
+ get project() {
72
+ return cache.project ??= new GoogleAuth().getProjectId();
73
+ }
74
+ });
17
75
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGjD;;GAEG;AACH,MAAM,KAAK,GAA0D,EAAE,CAAC;AAGxE,wHAAwH;AAExH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,SAAS,CAAC;IAE5B;;;;;;;;OAQG;IACH,IAAI,KAAK;QAER,OAAO,KAAK,CAAC,KAAK,KAAK,eAAe,EAAE,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE9E,CAAC;IAED;;;;;OAKG;IACH,IAAI,IAAI;QAEP,OAAO,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IAExD,CAAC;IAED;;;;;;OAMG;IACH,IAAI,OAAO;QAEV,OAAO,KAAK,CAAC,OAAO,KAAK,IAAI,UAAU,EAAE,CAAC,YAAY,EAAE,CAAC;IAE1D,CAAC;CAED,CAAC,CAAC"}
@@ -0,0 +1,33 @@
1
+ import { Vault } from "@metreeca/gear/vault";
2
+ /**
3
+ * Creates a Secret Manager vault.
4
+ *
5
+ * Parameters are looked up among the secrets of the project the process is authenticated against as each request is
6
+ * served, so that a secret created or rotated after the vault was constructed is retrieved as well. Each lookup
7
+ * returns the payload of the latest version of the secret, under the naming constraints {@link secret} defines.
8
+ *
9
+ * @returns A vault retrieving parameters from the Secret Manager of the project the process is authenticated against
10
+ *
11
+ * @throws {@link !Error Error} While retrieving a parameter, under the conditions listed by {@link secret}
12
+ */
13
+ export declare function createGCPVault(): Vault;
14
+ /**
15
+ * Reads a secret.
16
+ *
17
+ * Retrieves the payload of the latest version of a secret from the Secret Manager of the project the process is
18
+ * authenticated against.
19
+ *
20
+ * Secret names are limited to letters, digits, underscores and hyphens: a `key` carrying any other character names no
21
+ * secret and is reported as a failure.
22
+ *
23
+ * @param key The name of the secret to be read
24
+ *
25
+ * @returns A promise resolving to the textual payload of the latest version of the secret named `key`
26
+ *
27
+ * @throws {@link !Error Error} If `key` names no secret, if the secret is not accessible, or if its latest version
28
+ * carries no payload
29
+ *
30
+ * @see {@link https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets Accessing secrets}
31
+ */
32
+ export declare function secret(key: string): Promise<string>;
33
+ //# sourceMappingURL=secrets.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAkB7C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,KAAK,CAItC;AAKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqCzD"}
@@ -0,0 +1,106 @@
1
+ /*
2
+ * Copyright © 2026 Metreeca srl
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+ /**
17
+ * Secret Manager parameter lookup.
18
+ *
19
+ * Looks up credentials, API keys and other sensitive parameters among the secrets stored in Google Cloud Secret
20
+ * Manager. The project is discovered from the ambient Google Cloud credentials, with no configuration required.
21
+ *
22
+ * @module
23
+ *
24
+ * @remarks
25
+ *
26
+ * Secrets are read from the project the ambient credentials resolve to and no other: no configuration is available to
27
+ * target a different project, so a task reading its secrets has to be executed under credentials for that project.
28
+ *
29
+ * The Secret Manager client is created when the module is first imported and retained for the lifetime of the process:
30
+ * the gRPC channel it opens is never closed and keeps the event loop alive, so a short-lived task may have to exit
31
+ * explicitly once its work is done, rather than wait for the process to terminate on its own.
32
+ *
33
+ * @see {@link https://cloud.google.com/nodejs/docs/reference/secret-manager/latest Secret Manager Node.js Client}
34
+ * @see {@link https://cloud.google.com/nodejs/docs/reference/secret-manager/latest/secret-manager/v1.secretmanagerserviceclient SecretManagerServiceClient}
35
+ */
36
+ import { SecretManagerServiceClient } from "@google-cloud/secret-manager";
37
+ import { error } from "@metreeca/core";
38
+ /**
39
+ * The gRPC status code reporting a secret or a secret version that doesn't exist.
40
+ *
41
+ * @see {@link https://grpc.io/docs/guides/status-codes/ gRPC status codes}
42
+ */
43
+ const NOT_FOUND = 5;
44
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
45
+ const client = new SecretManagerServiceClient();
46
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
47
+ /**
48
+ * Creates a Secret Manager vault.
49
+ *
50
+ * Parameters are looked up among the secrets of the project the process is authenticated against as each request is
51
+ * served, so that a secret created or rotated after the vault was constructed is retrieved as well. Each lookup
52
+ * returns the payload of the latest version of the secret, under the naming constraints {@link secret} defines.
53
+ *
54
+ * @returns A vault retrieving parameters from the Secret Manager of the project the process is authenticated against
55
+ *
56
+ * @throws {@link !Error Error} While retrieving a parameter, under the conditions listed by {@link secret}
57
+ */
58
+ export function createGCPVault() {
59
+ return secret;
60
+ }
61
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
62
+ /**
63
+ * Reads a secret.
64
+ *
65
+ * Retrieves the payload of the latest version of a secret from the Secret Manager of the project the process is
66
+ * authenticated against.
67
+ *
68
+ * Secret names are limited to letters, digits, underscores and hyphens: a `key` carrying any other character names no
69
+ * secret and is reported as a failure.
70
+ *
71
+ * @param key The name of the secret to be read
72
+ *
73
+ * @returns A promise resolving to the textual payload of the latest version of the secret named `key`
74
+ *
75
+ * @throws {@link !Error Error} If `key` names no secret, if the secret is not accessible, or if its latest version
76
+ * carries no payload
77
+ *
78
+ * @see {@link https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets Accessing secrets}
79
+ */
80
+ export async function secret(key) {
81
+ try {
82
+ const name = client.secretVersionPath(await client.getProjectId(), key, "latest");
83
+ const [version] = await client.accessSecretVersion({ name });
84
+ const value = version.payload?.data?.toString();
85
+ return value ?? error(`undefined secret <${key}>`);
86
+ }
87
+ catch (e) {
88
+ if (missing(e)) {
89
+ throw error(`unknown secret <${key}>`);
90
+ }
91
+ else {
92
+ throw error(`failed to access secret <${key}>: ${e}`);
93
+ }
94
+ }
95
+ /**
96
+ * Checks if a failure reports a missing secret.
97
+ *
98
+ * @param cause The failure reported while accessing a secret
99
+ *
100
+ * @returns `true` if `cause` carries the {@link NOT_FOUND} gRPC status code; `false` otherwise
101
+ */
102
+ function missing(cause) {
103
+ return typeof cause === "object" && cause !== null && "code" in cause && cause.code === NOT_FOUND;
104
+ }
105
+ }
106
+ //# sourceMappingURL=secrets.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAIvC;;;;GAIG;AACH,MAAM,SAAS,GAAG,CAAC,CAAC;AAGpB,wHAAwH;AAExH,MAAM,MAAM,GAAG,IAAI,0BAA0B,EAAE,CAAC;AAGhD,wHAAwH;AAExH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc;IAE7B,OAAO,MAAM,CAAC;AAEf,CAAC;AAGD,wHAAwH;AAExH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,GAAW;IAEvC,IAAI,CAAC;QAEJ,MAAM,IAAI,GAAG,MAAM,CAAC,iBAAiB,CAAC,MAAM,MAAM,CAAC,YAAY,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QAClF,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAEhD,OAAO,KAAK,IAAI,KAAK,CAAC,qBAAqB,GAAG,GAAG,CAAC,CAAC;IAEpD,CAAC;IAAC,OAAQ,CAAC,EAAG,CAAC;QAEd,IAAK,OAAO,CAAC,CAAC,CAAC,EAAG,CAAC;YAElB,MAAM,KAAK,CAAC,mBAAmB,GAAG,GAAG,CAAC,CAAC;QAExC,CAAC;aAAM,CAAC;YAEP,MAAM,KAAK,CAAC,4BAA4B,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;QAEvD,CAAC;IAEF,CAAC;IAED;;;;;;OAMG;IACH,SAAS,OAAO,CAAC,KAAc;QAE9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;IAEnG,CAAC;AAEF,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@metreeca/gear-gcp",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Google Cloud service implementations for @metreeca/gear.",
5
5
  "keywords": [
6
6
  "typescript",
@@ -31,6 +31,10 @@
31
31
  ".": {
32
32
  "@metreeca/source": "./src/index.ts",
33
33
  "default": "./dist/index.js"
34
+ },
35
+ "./secrets": {
36
+ "@metreeca/source": "./src/secrets.ts",
37
+ "default": "./dist/secrets.js"
34
38
  }
35
39
  },
36
40
  "files": [
@@ -42,12 +46,16 @@
42
46
  "node": ">=22.22.0"
43
47
  },
44
48
  "scripts": {
45
- "clean": "rm -rf dist docs node_modules",
46
- "build": "rm -rf dist && tsc -p tsconfig.build.json",
49
+ "clean": "rm dist docs node_modules",
50
+ "build": "rm dist && tsc -p tsconfig.build.json",
47
51
  "check": "npx vitest --typecheck run"
48
52
  },
49
53
  "dependencies": {
50
- "@metreeca/gear": "^0.3.0"
54
+ "@google-cloud/secret-manager": "^7.2.0",
55
+ "@metreeca/core": "^0.13.0",
56
+ "@metreeca/gear": "^0.4.0",
57
+ "gcp-metadata": "^9.2.1",
58
+ "google-auth-library": "^11.3.1"
51
59
  },
52
60
  "devDependencies": {
53
61
  "@types/node": "^25.9.3",