@travetto/cli 5.0.10 → 5.0.12

package/README.md

@@ -171,7 +171,7 @@ Options:
 $ trv basic:arg 20
 
 Execution failed:
- * Argument volume is bigger than (10)
+ * Argument volume is greater than (10)
 
 Usage: basic:arg [options] [volume:number]
 
@@ -234,7 +234,7 @@ $ trv basic:arglist 10 5 3 9 8 1
 $ trv basic:arglist 10 5 3 9 20 1
 
 Execution failed:
- * Argument volumes[4] is bigger than (10)
+ * Argument volumes[4] is greater than (10)
 
 Usage: basic:arglist [options] <volumes...:number>
 
@@ -533,3 +533,62 @@ async validate(): Promise<CliValidationError | undefined> {
     }
   }
 ```
+
+## CLI - service
+The module provides the ability to start/stop/restart services as [docker](https://www.docker.com/community-edition) containers.  This is meant to be used for development purposes, to minimize the effort of getting an application up and running.  Services can be targeted individually or handled as a group.
+
+**Terminal: Command Service**
+```bash
+$ trv service --help
+
+Usage: service [options] <action:restart|start|status|stop> [services...:string]
+
+Options:
+  -h, --help  display help for command
+
+Available Services
+--------------------
+ * dynamodb@2.0.0
+ * elasticsearch@8.9.1
+ * firestore@latest
+ * mongodb@7.0
+ * mysql@8.0
+ * postgresql@15.4
+ * redis@7.2
+ * s3@3.1.0
+```
+
+A sample of all services available to the entire framework:
+
+**Terminal: All Services**
+```bash
+$ trv service status
+
+Service          Version    Status
+-------------------------------------------------
+dynamodb           2.0.0    Running 93af422e793a
+elasticsearch      8.9.1    Running ed76ee063d13
+firestore         latest    Running feec2e5e95b4
+mongodb              7.0    Running 5513eba6734e
+mysql                8.0    Running 307bc66d442a
+postgresql          15.4    Running e78291e71040
+redis                7.2    Running 77ba279b4e30
+s3                 3.1.0    Running fdacfc55b9e3
+```
+
+### Defining new Services
+The services are defined as plain typescript files within the framework and can easily be extended:
+
+**Code: Sample Service Definition**
+```typescript
+import type { ServiceDescriptor } from '@travetto/cli';
+
+const version = process.env.MONGO_VERSION ?? '7.0';
+
+export const service: ServiceDescriptor = {
+  name: 'mongodb',
+  version,
+  port: 27017,
+  image: `mongo:${version}`
+};
+```

package/__index__.ts

@@ -10,4 +10,5 @@ export * from './src/color';
 export * from './src/module';
 export * from './src/scm';
 export * from './src/parse';
+export * from './src/service';
 export * from './src/util';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/cli",
-  "version": "5.0.10",
+  "version": "5.0.12",
   "description": "CLI infrastructure for Travetto framework",
   "keywords": [
     "cli",
@@ -28,8 +28,8 @@
     "directory": "module/cli"
   },
   "dependencies": {
-    "@travetto/schema": "^5.0.10",
-    "@travetto/terminal": "^5.0.10"
+    "@travetto/schema": "^5.0.11",
+    "@travetto/terminal": "^5.0.11"
   },
   "travetto": {
     "displayName": "Command Line Interface",

package/src/error.ts

@@ -54,7 +54,7 @@ export class CliValidationResultError extends AppError<{ errors: CliValidationEr
   command: CliCommandShape;
 
   constructor(command: CliCommandShape, errors: CliValidationError[]) {
-    super('', undefined, { errors });
+    super('', { details: { errors } });
     this.command = command;
   }
 }

package/src/scm.ts

@@ -50,7 +50,7 @@ export class CliScmUtil {
     const ws = Runtime.workspace.path;
     const res = await ExecUtil.getResult(spawn('git', ['diff', '--name-only', `${fromHash}..${toHash}`, ':!**/DOC.*', ':!**/README.*'], { cwd: ws }), { catch: true });
     if (!res.valid) {
-      throw new AppError('Unable to detect changes between', 'data', { fromHash, toHash, output: (res.stderr || res.stdout) });
+      throw new AppError('Unable to detect changes between', { category: 'data', details: { fromHash, toHash, output: (res.stderr || res.stdout) } });
     }
     const out = new Set<string>();
     for (const line of res.stdout.split(/\n/g)) {

package/src/service.ts

@@ -0,0 +1,157 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import rl from 'node:readline/promises';
+import net from 'node:net';
+
+import { ExecUtil, TimeUtil, Util } from '@travetto/runtime';
+
+const ports = (val: number | `${number}:${number}`): [number, number] =>
+  typeof val === 'number' ?
+    [val, val] :
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    val.split(':').map(x => parseInt(x, 10)) as [number, number];
+
+type BodyCheck = (body: string) => boolean;
+
+/**
+ * This represents the schema for defined services
+ */
+export interface ServiceDescriptor {
+  name: string;
+  version: string | number;
+  port?: number | `${number}:${number}`;
+  privileged?: boolean;
+  image: string;
+  args?: string[];
+  ready?: { url: string, test?: BodyCheck };
+  volumes?: Record<string, string>;
+  env?: Record<string, string>;
+  startupTimeout?: number;
+}
+
+export type ServiceAction = 'start' | 'stop' | 'status' | 'restart';
+
+/**
+ * Service runner
+ */
+export class ServiceRunner {
+
+  constructor(public svc: ServiceDescriptor) { }
+
+  async #isRunning(full = false): Promise<boolean> {
+    const port = ports(this.svc.port!)[0];
+    const start = Date.now();
+    const timeoutMs = TimeUtil.asMillis(full ? this.svc.startupTimeout ?? 5000 : 100);
+    while ((Date.now() - start) < timeoutMs) {
+      try {
+        const sock = net.createConnection(port, 'localhost');
+        await new Promise<void>((res, rej) =>
+          sock.on('connect', res).on('timeout', rej).on('error', rej)
+        ).finally(() => sock.destroy());
+
+        if (!this.svc.ready?.url || !full) {
+          return true;
+        } else {
+          const req = await fetch(this.svc.ready.url, { method: 'GET' });
+          const text = await req.text();
+          if (req.ok && (this.svc.ready.test?.(text) ?? true)) {
+            return true;
+          }
+        }
+      } catch {
+        await Util.blockingTimeout(50);
+      }
+    }
+
+    return false;
+  }
+
+  async #hasImage(): Promise<boolean> {
+    const result = await ExecUtil.getResult(spawn('docker', ['image', 'inspect', this.svc.image], { shell: false }), { catch: true });
+    return result.valid;
+  }
+
+  async * #pullImage(): AsyncIterable<string> {
+    const proc = spawn('docker', ['pull', this.svc.image], { stdio: [0, 'pipe', 'pipe'] });
+    yield* rl.createInterface(proc.stdout!);
+    await ExecUtil.getResult(proc);
+  }
+
+  async #startContainer(): Promise<string> {
+    const args = [
+      'run',
+      '--rm',
+      '--detach',
+      ...this.svc.privileged ? ['--privileged'] : [],
+      '--label', `trv-${this.svc.name}`,
+      ...Object.entries(this.svc.env ?? {}).flatMap(([k, v]) => ['--env', `${k}=${v}`]),
+      ...this.svc.port ? ['-p', ports(this.svc.port).join(':')] : [],
+      ...Object.entries(this.svc.volumes ?? {}).flatMap(([k, v]) => ['--volume', `${k}:${v}`]),
+      this.svc.image,
+      ...this.svc.args ?? [],
+    ];
+
+    for (const item of Object.keys(this.svc.volumes ?? {})) {
+      await fs.mkdir(item, { recursive: true });
+    }
+
+    return (await ExecUtil.getResult(spawn('docker', args, { shell: false, stdio: [0, 'pipe', 2] }))).stdout;
+  }
+
+  async #getContainerId(): Promise<string | undefined> {
+    return (await ExecUtil.getResult(spawn('docker', ['ps', '-q', '--filter', `label=trv-${this.svc.name}`], { shell: false }))).stdout.trim();
+  }
+
+  async #killContainer(cid: string): Promise<void> {
+    await ExecUtil.getResult(spawn('docker', ['kill', cid], { shell: false }));
+  }
+
+  async * action(op: ServiceAction): AsyncIterable<['success' | 'failure' | 'message', string]> {
+    try {
+      const cid = await this.#getContainerId();
+      const port = this.svc.port ? ports(this.svc.port)[0] : 0;
+      const running = !!cid && (!port || await this.#isRunning());
+
+      if (running && !cid) { // We don't own
+        return yield [op === 'status' ? 'message' : 'failure', 'Running but not managed'];
+      }
+
+      if (op === 'status') {
+        return yield !cid ? ['message', 'Not running'] : ['success', `Running ${cid}`];
+      } else if (op === 'start' && running) {
+        return yield ['message', 'Skipping, already running'];
+      } else if (op === 'stop' && !running) {
+        return yield ['message', 'Skipping, already stopped'];
+      }
+
+      if (running && (op === 'restart' || op === 'stop')) {
+        yield ['message', 'Stopping'];
+        await this.#killContainer(cid);
+        yield ['success', 'Stopped'];
+      }
+
+      if (op === 'restart' || op === 'start') {
+        if (!await this.#hasImage()) {
+          yield ['message', 'Starting image download'];
+          for await (const line of await this.#pullImage()) {
+            yield ['message', `Downloading: ${line}`];
+          }
+          yield ['message', 'Image download complete'];
+        }
+
+        yield ['message', 'Starting'];
+        const out = await this.#startContainer();
+
+        if (port) {
+          yield ['message', `Waiting for ${this.svc.ready?.url ?? 'container'}...`];
+          if (!await this.#isRunning(true)) {
+            yield ['failure', 'Failed to start service correctly'];
+          }
+        }
+        yield ['success', `Started ${out.substring(0, 12)}`];
+      }
+    } catch {
+      yield ['failure', 'Failed to start'];
+    }
+  }
+}

package/support/cli.service.ts

@@ -0,0 +1,71 @@
+import { CliCommandShape, CliCommand, cliTpl, CliValidationError } from '@travetto/cli';
+import { Terminal } from '@travetto/terminal';
+import { AsyncQueue, Runtime, RuntimeIndex, Util } from '@travetto/runtime';
+
+import { ServiceRunner, ServiceDescriptor, ServiceAction } from '../src/service';
+
+/**
+ * Allows for running services
+ */
+@CliCommand()
+export class CliServiceCommand implements CliCommandShape {
+
+  async #getServices(services: string[]): Promise<ServiceDescriptor[]> {
+    return (await Promise.all(
+      RuntimeIndex.find({
+        module: m => m.roles.includes('std'),
+        folder: f => f === 'support',
+        file: f => /support\/service[.]/.test(f.sourceFile)
+      })
+        .map(x => Runtime.importFrom<{ service: ServiceDescriptor }>(x.import).then(v => v.service))
+    ))
+      .filter(x => !!x)
+      .filter(x => services?.length ? services.includes(x.name) : true)
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  async validate(action: ServiceAction, services: string[]): Promise<CliValidationError | undefined> {
+    const all = await this.#getServices(services);
+
+    if (!all.length) {
+      return { message: 'No services found' };
+    }
+  }
+
+  async help(): Promise<string[]> {
+    const all = await this.#getServices([]);
+    return [
+      cliTpl`${{ title: 'Available Services' }}`,
+      '-'.repeat(20),
+      ...all.map(x => cliTpl` * ${{ identifier: x.name }}@${{ type: x.version }}`)
+    ];
+  }
+
+  async main(action: ServiceAction, services: string[] = []): Promise<void> {
+    const all = await this.#getServices(services);
+    const maxName = Math.max(...all.map(x => x.name.length), 'Service'.length) + 3;
+    const maxVersion = Math.max(...all.map(x => `${x.version}`.length), 'Version'.length) + 3;
+    const maxStatus = 20;
+    const q = new AsyncQueue<{ idx: number, text: string, done?: boolean }>();
+
+    const jobs = all.map(async (v, i) => {
+      const identifier = v.name.padEnd(maxName);
+      const type = `${v.version}`.padStart(maxVersion - 3).padEnd(maxVersion);
+      for await (const [valueType, value] of new ServiceRunner(v).action(action)) {
+        const details = { [valueType === 'message' ? 'subtitle' : valueType]: value };
+        q.add({ idx: i, text: cliTpl`${{ identifier }} ${{ type }} ${details}` });
+      }
+    });
+
+    Promise.all(jobs).then(() => Util.queueMacroTask()).then(() => q.close());
+
+    const term = new Terminal();
+    await term.writer.writeLines([
+      '',
+      cliTpl`${{ title: 'Service'.padEnd(maxName) }} ${{ title: 'Version'.padEnd(maxVersion) }} ${{ title: 'Status' }}`,
+      ''.padEnd(maxName + maxVersion + maxStatus + 3, '-'),
+    ]).commit();
+
+    await term.streamList(q);
+  }
+}