openlattice-cloudrun 0.0.3

package/README.md

@@ -0,0 +1,137 @@
+# openlattice-cloudrun
+
+Google Cloud Run compute provider for [OpenLattice](../../README.md). Deploys containers as fully managed Cloud Run services, with exec via Cloud Run Jobs and logs via Cloud Logging.
+
+## Install
+
+```bash
+npm install openlattice openlattice-cloudrun
+```
+
+## Quick Start
+
+```typescript
+import { OpenLattice } from "openlattice";
+import { CloudRunProvider } from "openlattice-cloudrun";
+
+const lattice = new OpenLattice({
+  providers: [
+    new CloudRunProvider({
+      projectId: "my-gcp-project",
+      region: "us-central1",
+      authMethod: "metadata", // or "service-account" / "token"
+    }),
+  ],
+});
+
+const node = await lattice.provision(
+  {
+    runtime: { image: "gcr.io/my-project/my-app:latest" },
+    cpu: { cores: 1 },
+    memory: { sizeGiB: 0.5 },
+    network: { ports: [{ port: 8080 }] },
+  },
+  { id: "agent-1", type: "agent" }
+);
+
+const result = await lattice.exec(node.id, ["python", "-c", "print('hello')"]);
+console.log(result.stdout);
+
+await lattice.destroy(node.id);
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `projectId` | `string` | *required* | GCP project ID |
+| `region` | `string` | `"us-central1"` | Cloud Run region |
+| `authMethod` | `"metadata" \| "service-account" \| "token"` | `"metadata"` | Authentication method |
+| `serviceAccountKeyPath` | `string` | — | Path to SA key JSON (when `authMethod` is `"service-account"`) |
+| `accessToken` | `string` | — | Static token (when `authMethod` is `"token"`). Also reads `GOOGLE_ACCESS_TOKEN` env var |
+| `maxInstances` | `number` | `1` | Max instance count per service |
+| `minInstances` | `number` | `0` | Min instances (0 = scale-to-zero) |
+| `concurrency` | `number` | `80` | Request concurrency per instance |
+| `serviceAccount` | `string` | — | Service account email for the Cloud Run service identity |
+| `vpcConnector` | `string` | — | VPC connector name for private networking |
+| `defaultLabels` | `Record<string, string>` | — | Labels applied to all services |
+
+## Authentication
+
+Three methods are supported:
+
+**Metadata server** (default) — for code running on GCP (GCE, GKE, Cloud Run, etc.):
+```typescript
+new CloudRunProvider({ projectId: "my-project" })
+```
+
+**Service account key** — for local development or CI:
+```typescript
+new CloudRunProvider({
+  projectId: "my-project",
+  authMethod: "service-account",
+  serviceAccountKeyPath: "/path/to/key.json",
+})
+```
+
+**Static token** — for short-lived scripts or testing:
+```typescript
+new CloudRunProvider({
+  projectId: "my-project",
+  authMethod: "token",
+  accessToken: "ya29.a0...",
+})
+```
+
+Tokens are cached with a 5-minute expiry buffer and refreshed automatically.
+
+## Capabilities
+
+| Capability | Supported |
+|------------|-----------|
+| Provision / Exec / Destroy | Yes |
+| Stop / Start | Yes (via traffic routing) |
+| Pause / Resume | No |
+| Snapshots | No |
+| GPU | No |
+| Logs | Yes (Cloud Logging, with follow mode) |
+| Tailscale | No |
+| File Operations | No |
+| Persistent Storage | No |
+
+## How It Works
+
+### Provision
+Creates a Cloud Run service via the Admin API v2. Maps `ComputeSpec` fields to the service template (image, CPU, memory, ports, env, scaling). Configures startup and liveness probes on `/health`. Polls the long-running operation until the service is ready, then returns the service's HTTPS endpoint.
+
+### Exec
+Cloud Run services don't support shell exec. Instead, the provider creates a one-off **Cloud Run Job** using the same container image, runs it, retrieves stdout/stderr from **Cloud Logging**, then cleans up the job. Supports `cwd`, `env`, and `timeoutMs` options.
+
+### Stop / Start
+Implemented via traffic routing. Stop patches traffic to 0% (the service still exists but receives no requests). Start restores traffic to 100%.
+
+### Logs
+Queries the Cloud Logging API for entries matching the service. Supports `tail`, `since`, and `follow` options. Follow mode polls every 2 seconds for new entries.
+
+### Cost Estimation
+`getCost()` returns a rough estimate based on Cloud Run per-second pricing for vCPU and memory, computed from the service's resource limits and uptime since creation.
+
+## Required GCP Permissions
+
+The authenticated principal needs these IAM roles (or equivalent permissions):
+
+- `roles/run.admin` — create, update, delete Cloud Run services and jobs
+- `roles/logging.viewer` — read logs from Cloud Logging
+
+## Development
+
+```bash
+npm run build    # Compile TypeScript
+npm run test     # Run unit tests (mocked, no GCP needed)
+```
+
+Integration tests require a real GCP project:
+
+```bash
+CLOUDRUN_PROJECT_ID=my-project CLOUDRUN_ACCESS_TOKEN=ya29... npm run test:integration
+```

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Manages GCP access token acquisition and caching.
+ * Supports metadata server, service account key, and static token methods.
+ */
+export declare class GcpAuthManager {
+    private readonly authMethod;
+    private readonly serviceAccountKeyPath?;
+    private readonly staticToken?;
+    private cachedToken;
+    /** Buffer before token expiry to trigger refresh (5 minutes). */
+    private static readonly EXPIRY_BUFFER_MS;
+    constructor(opts: {
+        authMethod?: "metadata" | "service-account" | "token";
+        serviceAccountKeyPath?: string;
+        accessToken?: string;
+    });
+    /** Returns a valid access token, refreshing if necessary. */
+    getToken(): Promise<string>;
+    private fetchFromMetadata;
+    private fetchFromServiceAccount;
+}

package/dist/auth.js

@@ -0,0 +1,130 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GcpAuthManager = void 0;
+const fs = __importStar(require("fs"));
+const crypto = __importStar(require("crypto"));
+/**
+ * Manages GCP access token acquisition and caching.
+ * Supports metadata server, service account key, and static token methods.
+ */
+class GcpAuthManager {
+    constructor(opts) {
+        this.cachedToken = null;
+        this.authMethod = opts.authMethod ?? "metadata";
+        this.serviceAccountKeyPath = opts.serviceAccountKeyPath;
+        this.staticToken =
+            opts.accessToken ?? process.env.GOOGLE_ACCESS_TOKEN ?? undefined;
+        if (this.authMethod === "service-account" && !this.serviceAccountKeyPath) {
+            throw new Error("[cloudrun] serviceAccountKeyPath is required when authMethod is 'service-account'");
+        }
+        if (this.authMethod === "token" && !this.staticToken) {
+            throw new Error("[cloudrun] accessToken or GOOGLE_ACCESS_TOKEN env var is required when authMethod is 'token'");
+        }
+    }
+    /** Returns a valid access token, refreshing if necessary. */
+    async getToken() {
+        if (this.authMethod === "token") {
+            return this.staticToken;
+        }
+        if (this.cachedToken && Date.now() < this.cachedToken.expiresAt) {
+            return this.cachedToken.token;
+        }
+        if (this.authMethod === "metadata") {
+            return this.fetchFromMetadata();
+        }
+        return this.fetchFromServiceAccount();
+    }
+    async fetchFromMetadata() {
+        const url = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token";
+        const response = await fetch(url, {
+            headers: { "Metadata-Flavor": "Google" },
+        });
+        if (!response.ok) {
+            throw new Error(`[cloudrun] metadata token request failed (${response.status}): ${await response.text()}`);
+        }
+        const data = (await response.json());
+        this.cachedToken = {
+            token: data.access_token,
+            expiresAt: Date.now() +
+                data.expires_in * 1000 -
+                GcpAuthManager.EXPIRY_BUFFER_MS,
+        };
+        return data.access_token;
+    }
+    async fetchFromServiceAccount() {
+        const keyData = JSON.parse(fs.readFileSync(this.serviceAccountKeyPath, "utf-8"));
+        const now = Math.floor(Date.now() / 1000);
+        const header = { alg: "RS256", typ: "JWT" };
+        const payload = {
+            iss: keyData.client_email,
+            scope: "https://www.googleapis.com/auth/cloud-platform",
+            aud: keyData.token_uri,
+            iat: now,
+            exp: now + 3600,
+        };
+        const encodedHeader = base64url(JSON.stringify(header));
+        const encodedPayload = base64url(JSON.stringify(payload));
+        const signatureInput = `${encodedHeader}.${encodedPayload}`;
+        const sign = crypto.createSign("RSA-SHA256");
+        sign.update(signatureInput);
+        const signature = sign.sign(keyData.private_key);
+        const encodedSignature = base64url(signature);
+        const jwt = `${signatureInput}.${encodedSignature}`;
+        const response = await fetch(keyData.token_uri, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: `grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=${jwt}`,
+        });
+        if (!response.ok) {
+            throw new Error(`[cloudrun] service account token exchange failed (${response.status}): ${await response.text()}`);
+        }
+        const data = (await response.json());
+        this.cachedToken = {
+            token: data.access_token,
+            expiresAt: Date.now() +
+                data.expires_in * 1000 -
+                GcpAuthManager.EXPIRY_BUFFER_MS,
+        };
+        return data.access_token;
+    }
+}
+exports.GcpAuthManager = GcpAuthManager;
+/** Buffer before token expiry to trigger refresh (5 minutes). */
+GcpAuthManager.EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+function base64url(input) {
+    const buf = typeof input === "string" ? Buffer.from(input) : input;
+    return buf.toString("base64url");
+}

package/dist/cloudrun-provider.d.ts

@@ -0,0 +1,28 @@
+import type { ComputeProvider, ComputeSpec, ExecOpts, ExecResult, ExtensionMap, HealthStatus, LogEntry, LogOpts, ProviderCapabilities, ProviderNode, ProviderNodeStatus } from "openlattice";
+import type { CloudRunProviderConfig } from "./types";
+export declare class CloudRunProvider implements ComputeProvider {
+    readonly name = "cloudrun";
+    readonly capabilities: ProviderCapabilities;
+    private readonly config;
+    private readonly region;
+    private readonly auth;
+    constructor(config: CloudRunProviderConfig);
+    provision(spec: ComputeSpec): Promise<ProviderNode>;
+    exec(externalId: string, command: string[], opts?: ExecOpts): Promise<ExecResult>;
+    destroy(externalId: string): Promise<void>;
+    inspect(externalId: string): Promise<ProviderNodeStatus>;
+    stop(externalId: string): Promise<void>;
+    start(externalId: string): Promise<void>;
+    logs(externalId: string, opts?: LogOpts): AsyncIterable<LogEntry>;
+    healthCheck(): Promise<HealthStatus>;
+    getCost(externalId: string): Promise<{
+        totalUsd: number;
+    }>;
+    getExtension<K extends keyof ExtensionMap>(externalId: string, extension: K): ExtensionMap[K] | undefined;
+    private cloudRunRequest;
+    private cloudRunJobRequest;
+    private pollOperation;
+    private fetchLogs;
+    private fetchJobLogs;
+    private createNetworkExtension;
+}