@capsulos/cli 0.0.0-stage → 0.1.0

package/src/forward.ts

@@ -0,0 +1,92 @@
+// `capsulos forward <id> <port>`: a local HTTP server that relays every
+// request (WebSockets included) to the same port inside the capsule, through
+// capsulod's /proxy. Opens the capsule's dev server at http://localhost:<port>
+// in your browser, with the capsule's auth headers added on the way.
+import { createServer, request as httpRequest, type IncomingMessage, type ServerResponse } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import type { Duplex } from 'node:stream';
+import { Capsule, type Provider } from '@capsulos/sdk';
+
+export interface ForwardOptions {
+  /** Port of the local listener; defaults to the capsule port. */
+  localPort?: number;
+  log?: (msg: string) => void;
+}
+
+export async function forward(provider: Provider, id: string, port: number, opts: ForwardOptions = {}): Promise<{ url: string; close: () => void }> {
+  const log = opts.log ?? (() => undefined);
+  const capsule = await Capsule.connect(provider, id);
+  const target = capsule.ports.connection(port);
+  const base = new URL(target.baseUrl);
+  const req = base.protocol === 'https:' ? httpsRequest : httpRequest;
+
+  const upstream = async (incoming: IncomingMessage, upgrade = false) => {
+    const headers: Record<string, string | string[] | undefined> = { ...incoming.headers, ...(await target.headers()) };
+    headers.host = base.host;
+    // Plain requests get a fresh keep-alive connection; an upgrade must keep
+    // its `Connection: Upgrade` so the far end switches protocols.
+    if (!upgrade) delete headers.connection;
+    return req({
+      protocol: base.protocol,
+      hostname: base.hostname,
+      port: base.port || undefined,
+      method: incoming.method,
+      path: base.pathname.replace(/\/$/, '') + (incoming.url ?? '/'),
+      headers,
+    });
+  };
+
+  const server = createServer(async (incoming: IncomingMessage, res: ServerResponse) => {
+    try {
+      const out = await upstream(incoming);
+      out.on('response', (r) => {
+        res.writeHead(r.statusCode ?? 502, r.headers);
+        r.pipe(res);
+      });
+      out.on('error', (err) => {
+        if (!res.headersSent) res.writeHead(502);
+        res.end(`forward: ${err.message}`);
+      });
+      incoming.pipe(out);
+    } catch (err) {
+      res.writeHead(502);
+      res.end(`forward: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  });
+
+  // WebSocket upgrades: hand the raw sockets to each other once upstream says 101.
+  server.on('upgrade', async (incoming: IncomingMessage, socket: Duplex, head: Buffer) => {
+    socket.on('error', () => socket.destroy());
+    try {
+      const out = await upstream(incoming, true);
+      out.on('upgrade', (r, upSocket, upHead) => {
+        const lines = [`HTTP/1.1 101 Switching Protocols`];
+        for (const [k, v] of Object.entries(r.headers)) if (v !== undefined) lines.push(`${k}: ${Array.isArray(v) ? v.join(', ') : v}`);
+        socket.write(lines.join('\r\n') + '\r\n\r\n');
+        if (upHead.length) socket.write(upHead);
+        // Either side dropping the connection just ends the other; nobody
+        // gets to crash the forwarder.
+        socket.on('error', () => upSocket.destroy());
+        upSocket.on('error', () => socket.destroy());
+        upSocket.pipe(socket).pipe(upSocket);
+      });
+      out.on('response', (r) => {
+        socket.end(`HTTP/1.1 ${r.statusCode} ${r.statusMessage}\r\n\r\n`);
+      });
+      out.on('error', () => socket.destroy());
+      if (head.length) out.write(head);
+      out.end();
+    } catch {
+      socket.destroy();
+    }
+  });
+
+  const localPort = opts.localPort ?? port;
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(localPort, '127.0.0.1', resolve);
+  });
+  const url = `http://localhost:${localPort}`;
+  log(`forwarding ${url} → capsule ${id} port ${port} (ctrl-c to stop)`);
+  return { url, close: () => server.close() };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { init, type InitOptions } from './init.js';
+export { templateBuild, assembleArtifact, resolveCapsulod, imageArn, type TemplateBuildOptions } from './template.js';
+export { loadConfig, saveConfig, configPath, credentialsFor, CONFIG_FILE, type CapsulosConfig } from './config.js';

package/src/init.ts

@@ -0,0 +1,125 @@
+// `capsulos init`: the one-time setup in an AWS account. Idempotent.
+//   - artifact bucket       capsulos-artifacts-<account>
+//   - build role            CapsulosBuildRole      (assumed by the image builder)
+//   - execution role        CapsulosExecutionRole  (assumed by every capsule)
+// Network connectors are deliberately not created here: they are an account
+// design decision (which VPC, which security group). Pass one with
+// --egress-connector to record it in capsulos.json.
+import { IAMClient, GetRoleCommand, CreateRoleCommand, PutRolePolicyCommand } from '@aws-sdk/client-iam';
+import { S3Client, HeadBucketCommand, CreateBucketCommand } from '@aws-sdk/client-s3';
+import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+import { credentialsFor, saveConfig, type CapsulosConfig } from './config.js';
+
+export interface InitOptions {
+  region: string;
+  profile?: string;
+  /** Buckets (names) the execution role may read and write: your capsules' S3 mounts. */
+  s3Buckets?: string[];
+  egressConnectorArn?: string;
+  log?: (msg: string) => void;
+}
+
+const BUILD_ROLE = 'CapsulosBuildRole';
+const EXEC_ROLE = 'CapsulosExecutionRole';
+const TAGS = [
+  { Key: 'Project', Value: 'capsulos' },
+  { Key: 'ManagedBy', Value: 'capsulos-cli' },
+];
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export async function init(opts: InitOptions): Promise<CapsulosConfig> {
+  const log = opts.log ?? (() => {});
+  const credentials = credentialsFor(opts.profile);
+  const clientOpts = { region: opts.region, credentials };
+  const sts = new STSClient(clientOpts);
+  const iam = new IAMClient(clientOpts);
+  const s3 = new S3Client(clientOpts);
+
+  const me = await sts.send(new GetCallerIdentityCommand({}));
+  const accountId = me.Account;
+  if (!accountId) throw new Error('could not resolve the AWS account id');
+  const bucket = `capsulos-artifacts-${accountId}`;
+
+  try {
+    await s3.send(new HeadBucketCommand({ Bucket: bucket }));
+    log(`bucket ${bucket} exists`);
+  } catch {
+    await s3.send(new CreateBucketCommand({ Bucket: bucket }));
+    log(`bucket ${bucket} created`);
+  }
+
+  const trust = JSON.stringify({
+    Version: '2012-10-17',
+    Statement: [
+      {
+        Effect: 'Allow',
+        Principal: { Service: 'lambda.amazonaws.com' },
+        Action: ['sts:AssumeRole', 'sts:TagSession'],
+      },
+    ],
+  });
+
+  let created = false;
+  const ensureRole = async (name: string, description: string) => {
+    try {
+      await iam.send(new GetRoleCommand({ RoleName: name }));
+      log(`role ${name} exists`);
+    } catch {
+      await iam.send(new CreateRoleCommand({ RoleName: name, AssumeRolePolicyDocument: trust, Description: description, Tags: TAGS }));
+      created = true;
+      log(`role ${name} created`);
+    }
+  };
+
+  await ensureRole(BUILD_ROLE, 'capsulos: assumed by the Lambda MicroVMs image builder');
+  await iam.send(
+    new PutRolePolicyCommand({
+      RoleName: BUILD_ROLE,
+      PolicyName: 'capsulos-build',
+      PolicyDocument: JSON.stringify({
+        Version: '2012-10-17',
+        Statement: [
+          { Effect: 'Allow', Action: ['s3:GetObject'], Resource: `arn:aws:s3:::${bucket}/*` },
+          { Effect: 'Allow', Action: ['logs:CreateLogGroup', 'logs:CreateLogStream', 'logs:PutLogEvents'], Resource: 'arn:aws:logs:*:*:*' },
+        ],
+      }),
+    }),
+  );
+
+  await ensureRole(EXEC_ROLE, 'capsulos: assumed by every capsule (S3 mounts)');
+  const buckets = opts.s3Buckets ?? [];
+  await iam.send(
+    new PutRolePolicyCommand({
+      RoleName: EXEC_ROLE,
+      PolicyName: 'capsulos-execution',
+      PolicyDocument: JSON.stringify({
+        Version: '2012-10-17',
+        Statement: buckets.length
+          ? [
+              { Effect: 'Allow', Action: ['s3:ListBucket'], Resource: buckets.map((b) => `arn:aws:s3:::${b}`) },
+              { Effect: 'Allow', Action: ['s3:GetObject', 's3:PutObject', 's3:DeleteObject'], Resource: buckets.map((b) => `arn:aws:s3:::${b}/*`) },
+            ]
+          : // IAM rejects an empty statement list; grant nothing explicitly.
+            [{ Effect: 'Deny', Action: ['s3:*'], Resource: '*', Sid: 'NoBucketsConfiguredYet' }],
+      }),
+    }),
+  );
+
+  log(buckets.length ? `execution role: S3 access to ${buckets.join(', ')}` : 'execution role: no S3 buckets (pass --s3-bucket)');
+  // IAM is eventually consistent: a capsule launched right after a policy
+  // change can still be refused for a few seconds.
+  log(created ? 'roles just created: waiting 10s for IAM to propagate' : 'policies updated: waiting 10s for IAM to propagate');
+  await sleep(10_000);
+
+  const cfg: CapsulosConfig = {
+    region: opts.region,
+    accountId,
+    bucket,
+    buildRoleArn: `arn:aws:iam::${accountId}:role/${BUILD_ROLE}`,
+    executionRoleArn: `arn:aws:iam::${accountId}:role/${EXEC_ROLE}`,
+    ...(opts.egressConnectorArn ? { egressConnectorArn: opts.egressConnectorArn } : {}),
+  };
+  const path = saveConfig(cfg);
+  log(`wrote ${path}`);
+  return cfg;
+}

package/src/shell.ts

@@ -0,0 +1,29 @@
+// `capsulos shell <id>`: your terminal, attached to a capsule's pty. Raw mode
+// so that every key (ctrl-c, arrows, tab) goes to the capsule; the session
+// ends when the remote shell exits.
+import { Capsule, type Provider } from '@capsulos/sdk';
+
+export async function shell(provider: Provider, id: string, cmd?: string): Promise<number> {
+  const capsule = await Capsule.connect(provider, id);
+  const { stdin, stdout } = process;
+  const size = () => ({ cols: stdout.columns || 80, rows: stdout.rows || 24 });
+  const term = await capsule.pty.open({ cmd, ...size(), onData: (chunk) => stdout.write(chunk) });
+
+  const onKey = (data: Buffer) => term.write(new Uint8Array(data));
+  const onResize = () => {
+    const s = size();
+    term.resize(s.cols, s.rows);
+  };
+  if (stdin.isTTY) stdin.setRawMode(true);
+  stdin.resume();
+  stdin.on('data', onKey);
+  stdout.on('resize', onResize);
+  try {
+    return await term.wait();
+  } finally {
+    stdin.off('data', onKey);
+    stdout.off('resize', onResize);
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdin.pause();
+  }
+}

package/src/template.test.ts

@@ -0,0 +1,35 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { assembleArtifact, imageArn } from './template.js';
+
+describe('assembleArtifact', () => {
+  it('zips the context with the Dockerfile and capsulod at the root', () => {
+    const ctx = mkdtempSync(join(tmpdir(), 'ctx-'));
+    writeFileSync(join(ctx, 'Dockerfile'), 'FROM debian\nCOPY capsulod /usr/local/bin/\n');
+    writeFileSync(join(ctx, 'app.py'), 'print(1)\n');
+    const bin = join(mkdtempSync(join(tmpdir(), 'bin-')), 'capsulod');
+    writeFileSync(bin, '#!/bin/sh\n');
+
+    const zip = assembleArtifact({ name: 't', context: ctx }, bin);
+    const zipPath = join(mkdtempSync(join(tmpdir(), 'z-')), 't.zip');
+    writeFileSync(zipPath, zip);
+    const listing = execFileSync('unzip', ['-Z1', zipPath]).toString();
+    expect(listing.split('\n').filter(Boolean).sort()).toEqual(['Dockerfile', 'app.py', 'capsulod']);
+  });
+
+  it('fails without a Dockerfile', () => {
+    const ctx = mkdtempSync(join(tmpdir(), 'ctx-'));
+    expect(() => assembleArtifact({ name: 't', context: ctx }, '/bin/true')).toThrow(/Dockerfile not found/);
+  });
+});
+
+describe('imageArn', () => {
+  it('builds the full ARN the API requires', () => {
+    expect(imageArn({ region: 'us-east-1', accountId: '123', bucket: '', buildRoleArn: '', executionRoleArn: '' }, 'python')).toBe(
+      'arn:aws:lambda:us-east-1:123:microvm-image:python',
+    );
+  });
+});

package/src/template.ts

@@ -0,0 +1,147 @@
+// `capsulos template build <name>`: a Dockerfile becomes a MicrovmImage.
+//   1. assemble a build context: the user's directory + Dockerfile + capsulod
+//   2. zip it and upload to the artifact bucket
+//   3. CreateMicrovmImage (or UpdateMicrovmImage → new version) with
+//      additionalOsCapabilities=ALL (mounts) and the /ready + /run hooks
+//   4. poll until CREATED/UPDATED
+// The Dockerfile must end up running capsulod on :8080 (see templates/base).
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import {
+  LambdaMicrovmsClient,
+  CreateMicrovmImageCommand,
+  UpdateMicrovmImageCommand,
+  GetMicrovmImageCommand,
+} from '@aws-sdk/client-lambda-microvms';
+import { credentialsFor, type CapsulosConfig } from './config.js';
+
+export interface TemplateBuildOptions {
+  name: string;
+  /** Directory with the Dockerfile (and anything it COPYs). */
+  context: string;
+  dockerfile?: string;
+  /** Prebuilt linux/arm64 capsulod; when omitted, built from --daemon-src with Go. */
+  capsulod?: string;
+  /** Path to the daemon's Go module (defaults to the monorepo's daemon/). */
+  daemonSrc?: string;
+  memoryMiB?: number;
+  profile?: string;
+  description?: string;
+  log?: (msg: string) => void;
+}
+
+const HOOKS_PORT = 9000;
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export function imageArn(cfg: CapsulosConfig, name: string): string {
+  return `arn:aws:lambda:${cfg.region}:${cfg.accountId}:microvm-image:${name}`;
+}
+
+/** Resolve or cross-compile capsulod for linux/arm64 (the service runs Graviton). */
+export function resolveCapsulod(opts: Pick<TemplateBuildOptions, 'capsulod' | 'daemonSrc' | 'log'>): string {
+  if (opts.capsulod) {
+    if (!existsSync(opts.capsulod)) throw new Error(`capsulod binary not found: ${opts.capsulod}`);
+    return resolve(opts.capsulod);
+  }
+  const here = dirname(fileURLToPath(import.meta.url));
+  const src = opts.daemonSrc ?? resolve(here, '..', '..', '..', 'daemon');
+  if (!existsSync(join(src, 'go.mod'))) {
+    throw new Error(
+      `no capsulod binary given and no daemon source at ${src}; pass --capsulod <path> (download capsulod-linux-arm64 from https://github.com/tornoai/capsulos/releases) or --daemon-src <dir>`,
+    );
+  }
+  const out = join(mkdtempSync(join(tmpdir(), 'capsulod-')), 'capsulod');
+  opts.log?.(`building capsulod for linux/arm64 from ${src}`);
+  execFileSync('go', ['build', '-trimpath', '-ldflags', '-s -w', '-o', out, './cmd/capsulod'], {
+    cwd: src,
+    env: { ...process.env, CGO_ENABLED: '0', GOOS: 'linux', GOARCH: 'arm64' },
+    stdio: 'inherit',
+  });
+  return out;
+}
+
+/** Build the zip the image builder consumes: context + Dockerfile + capsulod at the root. */
+export function assembleArtifact(opts: TemplateBuildOptions, capsulod: string): Buffer {
+  const context = resolve(opts.context);
+  const dockerfile = resolve(opts.dockerfile ?? join(context, 'Dockerfile'));
+  if (!existsSync(dockerfile)) throw new Error(`Dockerfile not found: ${dockerfile}`);
+  const stage = mkdtempSync(join(tmpdir(), 'capsulos-template-'));
+  try {
+    cpSync(context, stage, { recursive: true });
+    cpSync(dockerfile, join(stage, 'Dockerfile'));
+    cpSync(capsulod, join(stage, 'capsulod'));
+    const zipPath = join(stage, '..', `capsulos-${opts.name}.zip`);
+    rmSync(zipPath, { force: true });
+    execFileSync('zip', ['-q', '-r', '-X', zipPath, '.'], { cwd: stage });
+    return readFileSync(zipPath);
+  } finally {
+    rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+export async function templateBuild(cfg: CapsulosConfig, opts: TemplateBuildOptions): Promise<{ imageArn: string; version: string }> {
+  const log = opts.log ?? (() => {});
+  const credentials = credentialsFor(opts.profile);
+  const s3 = new S3Client({ region: cfg.region, credentials });
+  const mvm = new LambdaMicrovmsClient({ region: cfg.region, credentials });
+
+  const capsulod = resolveCapsulod(opts);
+  const zip = assembleArtifact(opts, capsulod);
+  const key = `templates/${opts.name}.zip`;
+  await s3.send(new PutObjectCommand({ Bucket: cfg.bucket, Key: key, Body: zip }));
+  log(`uploaded s3://${cfg.bucket}/${key} (${zip.length} bytes)`);
+
+  const arn = imageArn(cfg, opts.name);
+  const spec = {
+    codeArtifact: { uri: `s3://${cfg.bucket}/${key}` },
+    baseImageArn: `arn:aws:lambda:${cfg.region}:aws:microvm-image:al2023-1`,
+    buildRoleArn: cfg.buildRoleArn,
+    cpuConfigurations: [{ architecture: 'ARM_64' as const }],
+    resources: [{ minimumMemoryInMiB: opts.memoryMiB ?? 512 }],
+    // Verified: without this the capsule has Docker's capability set and
+    // cannot mount anything (docs/lambda-microvms-findings.md).
+    additionalOsCapabilities: ['ALL' as const],
+    hooks: {
+      port: HOOKS_PORT,
+      microvmHooks: { run: 'ENABLED' as const, runTimeoutInSeconds: 60 },
+      microvmImageHooks: { ready: 'ENABLED' as const, readyTimeoutInSeconds: 120 },
+    },
+  };
+
+  const t0 = Date.now();
+  try {
+    await mvm.send(
+      new CreateMicrovmImageCommand({
+        name: opts.name,
+        description: opts.description ?? `capsulos template ${opts.name}`,
+        tags: { project: 'capsulos' },
+        ...spec,
+      }),
+    );
+    log(`image ${arn} created; building…`);
+  } catch (err) {
+    if (err instanceof Error && err.name === 'ConflictException') {
+      await mvm.send(new UpdateMicrovmImageCommand({ imageIdentifier: arn, ...spec }));
+      log(`image ${arn} exists → new version; building…`);
+    } else {
+      throw err;
+    }
+  }
+
+  for (;;) {
+    await sleep(10_000);
+    const img = await mvm.send(new GetMicrovmImageCommand({ imageIdentifier: arn }));
+    const elapsed = ((Date.now() - t0) / 1000).toFixed(0);
+    log(`state=${img.state} (t+${elapsed}s)`);
+    if (img.state === 'CREATED' || img.state === 'UPDATED') {
+      return { imageArn: arn, version: String(img.latestActiveImageVersion ?? '') };
+    }
+    if (img.state?.endsWith('_FAILED')) {
+      throw new Error(`build failed: ${img.state} — see CloudWatch /aws/lambda-microvms/${opts.name}`);
+    }
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.