ninedeploy 0.18.4 → 0.18.11

package/src/commands/tunnel.ts

@@ -0,0 +1,218 @@
+import net from 'node:net';
+import process from 'node:process';
+import type { NineDeployClient } from '../client.js';
+import { c, error, info, success } from '../lib/format.js';
+import { plain } from './sources.js';
+
+/**
+ * G5.8 `ninedeploy tunnel db <id> [--port <n>] [--bind <address>]`: offer a
+ * database (on the panel host, or on a node with agent 0.18.7) on a local port. Each local connection opens its own
+ * WebSocket to `/v1/databases/:id/tunnel`, which carries it byte for byte to
+ * the database container, so the database port stays closed to the internet.
+ * Needs the database's admin role; the database's own login applies on top.
+ */
+
+/** Frames stay well under the server's 1 MiB WebSocket payload cap. */
+const MAX_FRAME = 64 * 1024;
+
+/** The parts of a `ws` WebSocket the tunnel uses (injectable for tests). */
+export interface TunnelSocket {
+  readonly readyState: number;
+  send(data: Uint8Array, opts: { binary: true }): void;
+  close(code?: number): void;
+  on(event: 'open', cb: () => void): void;
+  on(event: 'message', cb: (data: Buffer, isBinary: boolean) => void): void;
+  on(event: 'close', cb: (code: number, reason: Buffer) => void): void;
+  on(event: 'error', cb: (err: Error) => void): void;
+}
+export type TunnelSocketFactory = (url: string, protocols: string[]) => TunnelSocket;
+
+export interface TunnelOptions {
+  port?: string;
+  bind?: string;
+}
+
+export interface TunnelDeps {
+  socketFactory?: TunnelSocketFactory;
+  /** The bearer and the tunnel URL (defaults: the CLI config, refreshed when about to expire). */
+  credentials?: () => Promise<{ url: (path: string) => string; token: string }>;
+  /** Resolves once the tunnel is listening (tests); the command itself runs until Ctrl-C. */
+  onListening?: (address: { host: string; port: number }, server: net.Server) => void;
+}
+
+const OPEN = 1;
+
+async function defaultCredentials(): Promise<{ url: (path: string) => string; token: string }> {
+  const { loadConfig } = await import('../config.js');
+  const { apiUrl, refreshAccessToken, tokenExpiresSoon } = await import('../client.js');
+  if (tokenExpiresSoon(loadConfig().token)) await refreshAccessToken();
+  return { url: (path) => apiUrl(path).replace(/^http/, 'ws'), token: loadConfig().token ?? '' };
+}
+
+async function defaultSocketFactory(): Promise<TunnelSocketFactory> {
+  const { WebSocket } = await import('ws');
+  return (url, protocols) => new WebSocket(url, protocols) as unknown as TunnelSocket;
+}
+
+/** Carry one local connection over one tunnel WebSocket. */
+export function pipeConnection(local: net.Socket, ws: TunnelSocket, onRefused: (reason: string) => void): void {
+  const pending: Buffer[] = [];
+  const sendChunked = (chunk: Buffer) => {
+    for (let at = 0; at < chunk.length; at += MAX_FRAME) ws.send(chunk.subarray(at, at + MAX_FRAME), { binary: true });
+  };
+  local.on('data', (chunk: Buffer) => {
+    if (ws.readyState === OPEN) sendChunked(chunk);
+    else pending.push(chunk);
+  });
+  ws.on('open', () => {
+    for (const chunk of pending.splice(0)) sendChunked(chunk);
+  });
+  ws.on('message', (data, isBinary) => {
+    if (isBinary) local.write(data);
+  });
+  ws.on('close', (code, reason) => {
+    if (code === 1008) onRefused(String(reason ?? '') || 'refused');
+    else if (code !== 1000 && code !== 1005) onRefused(`closed (${code}${String(reason ?? '') ? `: ${String(reason)}` : ''})`);
+    local.destroy();
+  });
+  ws.on('error', () => local.destroy());
+  local.on('close', () => {
+    try {
+      ws.close(1000);
+    } catch {
+      /* already closed */
+    }
+  });
+  local.on('error', () => undefined);
+}
+
+/** Canonical decimal id only, as the server accepts it. */
+function parseId(raw: string | undefined): number {
+  const t = (raw ?? '').trim();
+  return /^[1-9]\d*$/.test(t) && Number.isSafeInteger(Number(t)) ? Number(t) : 0;
+}
+
+/** Listen locally and carry each connection over its own tunnel WebSocket to `path`. Null when it cannot listen. */
+async function serveTunnel(path: string, host: string, requested: number | undefined, preferred: number, deps: TunnelDeps): Promise<number | null> {
+  const creds = await (deps.credentials ?? defaultCredentials)();
+  const factory = deps.socketFactory ?? (await defaultSocketFactory());
+  const url = creds.url(path);
+  const open = () => factory(url, ['ninedeploy.tunnel.v1', `ninedeploy.bearer.${creds.token}`]);
+
+  let reported = '';
+  const server = net.createServer((local) => {
+    pipeConnection(local, open(), (reason) => {
+      // One line per distinct refusal: a client retrying would print it for every attempt.
+      if (reason === reported) return;
+      reported = reason;
+      error(`Tunnel refused: ${plain(reason)}`);
+    });
+  });
+
+  const listen = (port: number) =>
+    new Promise<number>((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, host, () => {
+        server.off('error', reject);
+        resolve((server.address() as net.AddressInfo).port);
+      });
+    });
+  // Default: the preferred port when it is free locally, else any free one.
+  let port: number;
+  try {
+    port = await listen(requested ?? preferred);
+  } catch (err) {
+    if (requested !== undefined) {
+      error(`Cannot listen on ${host}:${requested}: ${err instanceof Error ? err.message : String(err)}`);
+      return null;
+    }
+    port = await listen(0);
+  }
+  tunnelServers.set(port, server);
+  return port;
+}
+
+const tunnelServers = new Map<number, net.Server>();
+
+/** Hand the listening server to a test, or run until Ctrl-C. */
+async function untilInterrupted(host: string, port: number, deps: TunnelDeps): Promise<void> {
+  const server = tunnelServers.get(port)!;
+  tunnelServers.delete(port);
+  if (host !== '127.0.0.1' && host !== '::1') console.log(`  ${c.yellow(`⚠ Bound to ${host}: anyone who can reach this address can use the tunnel.`)}`);
+  info(c.dim('Ctrl-C closes the tunnel.'));
+  deps.onListening?.({ host, port }, server);
+  if (deps.onListening) return;
+  await new Promise<void>((resolve) => {
+    process.once('SIGINT', () => {
+      server.close();
+      resolve();
+    });
+  });
+}
+
+export async function tunnelDb(client: NineDeployClient, idRaw: string, opts: TunnelOptions = {}, deps: TunnelDeps = {}): Promise<void> {
+  const id = parseId(idRaw);
+  if (!id) return error('Usage: ninedeploy tunnel db <id> [--port <n>] [--bind <address>]');
+  const requested = opts.port === undefined ? undefined : Number(opts.port);
+  if (requested !== undefined && !(Number.isInteger(requested) && requested >= 0 && requested <= 65535)) {
+    return error('--port must be 0-65535 (0 picks a free one)');
+  }
+  const host = opts.bind ?? '127.0.0.1';
+  if (net.isIP(host) === 0) return error('--bind must be an IP address');
+
+  let detail: Awaited<ReturnType<NineDeployClient['databases']['get']>>;
+  try {
+    detail = await client.databases.get(id);
+  } catch (err) {
+    return error(plain(err instanceof Error ? err.message : String(err)));
+  }
+  const port = await serveTunnel(`/v1/databases/${id}/tunnel`, host, requested, detail.port ?? 0, deps);
+  if (port === null) return;
+
+  success(`Tunnel to ${plain(detail.name)} (${plain(detail.engine)}) listening on ${host}:${port}`);
+  info(`Connect your client to ${host}:${port} with the database's own credentials (Database page → Credentials).`);
+  await untilInterrupted(host, port, deps);
+}
+
+export interface ServiceTunnelOptions extends TunnelOptions {
+  /** The container port (default: the service port). */
+  target?: string;
+  replica?: string;
+}
+
+/**
+ * G5.8 `ninedeploy tunnel service <id> [--target <port>] [--replica <n>]
+ * [--port <n>] [--bind <address>]`: offer a port of a docker service (on
+ * the panel host, or on a node with agent 0.18.7) locally, for an admin port, a debugger or a service with no domain.
+ * Needs the service's admin role.
+ */
+export async function tunnelService(client: NineDeployClient, idRaw: string, opts: ServiceTunnelOptions = {}, deps: TunnelDeps = {}): Promise<void> {
+  const id = parseId(idRaw);
+  if (!id) return error('Usage: ninedeploy tunnel service <id> [--target <port>] [--replica <n>] [--port <n>] [--bind <address>]');
+  const requested = opts.port === undefined ? undefined : Number(opts.port);
+  if (requested !== undefined && !(Number.isInteger(requested) && requested >= 0 && requested <= 65535)) {
+    return error('--port must be 0-65535 (0 picks a free one)');
+  }
+  const target = opts.target === undefined ? undefined : Number(opts.target);
+  if (target !== undefined && !(Number.isInteger(target) && target >= 1 && target <= 65535)) return error('--target must be a container port, 1-65535');
+  const replica = opts.replica === undefined ? undefined : Number(opts.replica);
+  if (replica !== undefined && !(Number.isInteger(replica) && replica >= 1)) return error('--replica must be 1 or more');
+  const host = opts.bind ?? '127.0.0.1';
+  if (net.isIP(host) === 0) return error('--bind must be an IP address');
+
+  let svc: Awaited<ReturnType<NineDeployClient['services']['get']>>;
+  try {
+    svc = await client.services.get(id);
+  } catch (err) {
+    return error(plain(err instanceof Error ? err.message : String(err)));
+  }
+  const containerPort = target ?? svc.port ?? undefined;
+  if (!containerPort) return error('The service has no port; name the container port with --target <port>.');
+  const query = new URLSearchParams({ port: String(containerPort), ...(replica ? { replica: String(replica) } : {}) });
+  const port = await serveTunnel(`/v1/services/${id}/tunnel?${query.toString()}`, host, requested, containerPort, deps);
+  if (port === null) return;
+
+  success(`Tunnel to ${plain(svc.name)}:${containerPort}${replica ? ` (replica ${replica})` : ''} listening on ${host}:${port}`);
+  info('It reaches the container directly, past what the service domains enforce.');
+  await untilInterrupted(host, port, deps);
+}

package/src/index.ts

@@ -66,6 +66,7 @@ import {
   terminalOpen, terminalsKill, terminalsList, terminalsShow, trafficService, trafficSettings, trafficSummary,
   type TerminalOpenOptions, type TerminalsListOptions,
 } from './commands/operations.js';
+import { tunnelDb, tunnelService, type ServiceTunnelOptions, type TunnelOptions } from './commands/tunnel.js';
 import {
   communityTemplatesImport,
   communityTemplatesList,
@@ -1081,12 +1082,16 @@ providersCmd.command('set-aws')
   .option('--disable', 'Disable the provider (references stay literal)')
   .action((opts: AwsCliOptions) => secretProvidersSetAws(getClient(), opts));
 providersCmd.command('test <kind>')
-  .description('Test a provider (vault | aws), optionally reading one secret')
+  .description('Test a provider (vault | aws | gcp | azure | onepassword | exec), optionally reading one secret')
   .option('--probe-path <path>', 'vault: also read this path (relative to the mount)')
   .option('--probe-secret-id <id>', 'aws: also read this secret')
-  .action((kind: string, opts: { probePath?: string; probeSecretId?: string }) => secretProvidersTest(getClient(), kind, opts));
+  .option('--probe-parameter <name>', 'aws: also read this Parameter Store parameter')
+  .option('--probe-name <name>', 'gcp, azure, onepassword, exec: also resolve this reference name')
+  .action((kind: string, opts: { probePath?: string; probeSecretId?: string; probeParameter?: string; probeName?: string }) =>
+    secretProvidersTest(getClient(), kind, opts),
+  );
 providersCmd.command('delete <kind>')
-  .description('Remove a provider (vault | aws); its references stay literal at deploy')
+  .description('Remove a provider (vault | aws | gcp | azure | onepassword | exec); its references stay literal at deploy')
   .alias('rm')
   .option('-y, --yes', 'Skip the confirmation prompt')
   .action((kind: string, opts: { yes?: boolean }) => secretProvidersDelete(getClient(), kind, opts));
@@ -1126,6 +1131,21 @@ terminalCmd.command('host [serverId]')
   .description('Root shell on the panel host or a node (off by default; asks for your password)')
   .action((serverId: string | undefined) => terminalOpen(getClient(), 'host', serverId));
 /* v8 ignore stop */
+const tunnelCmd = program.command('tunnel').description('Reach a database or a service port through the panel on a local port (G5.8)');
+/* v8 ignore start -- exercised by test/tunnel.test.ts. */
+tunnelCmd.command('db <id>')
+  .description('Offer a panel-host database on a local port; its port stays closed to the internet (database admin)')
+  .option('--port <n>', 'Local port (default: the engine port when free, else any free one; 0 picks one)')
+  .option('--bind <address>', 'Local address to listen on (default 127.0.0.1)')
+  .action((id: string, opts: TunnelOptions) => tunnelDb(getClient(), id, opts));
+tunnelCmd.command('service <id>')
+  .description('Offer a port of a panel-host docker service on a local port, past its domains (service admin)')
+  .option('--target <port>', 'Container port (default: the service port)')
+  .option('--replica <n>', 'Replica to reach (default 1)')
+  .option('--port <n>', 'Local port (default: the container port when free, else any free one; 0 picks one)')
+  .option('--bind <address>', 'Local address to listen on (default 127.0.0.1)')
+  .action((id: string, opts: ServiceTunnelOptions) => tunnelService(getClient(), id, opts));
+/* v8 ignore stop */
 const trafficCmd = program.command('traffic').description('Traffic analytics (opt-in)');
 /* v8 ignore start -- exercised by test/operations.test.ts. */
 trafficCmd.command('settings')
@@ -1387,7 +1407,7 @@ sources.command('list').description('List configured sources').action(() => sour
 sources.command('show <id>').description('Show one source in detail').action((id: string) => sourcesShow(getClient(), id));
 sources.command('add [name]')
   .description('Add a new source (interactive; PAT/SSH key from env or masked prompt)')
-  .option('--base-url <url>', 'Gitea base URL, e.g. https://git.example.com (enables the live test and repo list)')
+  .option('--base-url <url>', 'Gitea or self-hosted GitLab base URL, e.g. https://git.example.com (enables the live test and repo list)')
   .action((name: string | undefined, opts: { baseUrl?: string }) => sourcesAdd(getClient(), name, opts));
 sources.command('test [id]').description('Verify that a stored source token still authenticates').action((id?: string) => sourcesTest(getClient(), id));
 sources.command('keygen [id]').description('Generate an ed25519 deploy-key pair on the panel and print the public key').action((id?: string) => sourcesKeygen(getClient(), id));