neonctl 1.27.6 → 1.29.1

package/src/index.ts

@@ -0,0 +1,180 @@
+import { basename } from 'node:path';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import axiosDebug from 'axios-debug-log';
+axiosDebug({
+  request(debug, config) {
+    debug(`${config.method?.toUpperCase()} ${config.url}`);
+  },
+  response(debug, response) {
+    debug(`${response.status} ${response.statusText}`);
+  },
+  error(debug, error) {
+    debug(error);
+  },
+});
+import { Api } from '@neondatabase/api-client';
+
+import { ensureAuth } from './commands/auth.js';
+import { defaultDir, ensureConfigDir } from './config.js';
+import { log } from './log.js';
+import { defaultClientID } from './auth.js';
+import { fillInArgs } from './utils/middlewares.js';
+import pkg from './pkg.js';
+import commands from './commands/index.js';
+import { analyticsMiddleware, sendError } from './analytics.js';
+import { isAxiosError } from 'axios';
+import { matchErrorCode } from './errors.js';
+import { showHelp } from './help.js';
+import { currentContextFile, enrichFromContext } from './context.js';
+
+const NO_SUBCOMMANDS_VERBS = [
+  'auth',
+  'me',
+  'cs',
+  'connection-string',
+  'set-context',
+];
+
+let builder = yargs(hideBin(process.argv));
+builder = builder
+  .scriptName(pkg.name)
+  .locale('en')
+  .usage('$0 <command> [options]')
+  .parserConfiguration({
+    'populate--': true,
+  })
+  .help()
+  .option('output', {
+    alias: 'o',
+    group: 'Global options:',
+    describe: 'Set output format',
+    type: 'string',
+    choices: ['json', 'yaml', 'table'],
+    default: 'table',
+  })
+  .option('api-host', {
+    describe: 'The API host',
+    hidden: true,
+    default: process.env.NEON_API_HOST ?? 'https://console.neon.tech/api/v2',
+  })
+  // Setup config directory
+  .option('config-dir', {
+    describe: 'Path to config directory',
+    group: 'Global options:',
+    type: 'string',
+    default: defaultDir,
+  })
+  .option('force-auth', {
+    describe: 'Force authentication',
+    type: 'boolean',
+    hidden: true,
+    default: false,
+  })
+  .middleware(ensureConfigDir)
+  .options({
+    'oauth-host': {
+      description: 'URL to Neon OAuth host',
+      hidden: true,
+      default: process.env.NEON_OAUTH_HOST ?? 'https://oauth2.neon.tech',
+    },
+    'client-id': {
+      description: 'OAuth client id',
+      hidden: true,
+      type: 'string',
+      default: defaultClientID,
+    },
+    'api-key': {
+      describe: 'API key',
+      group: 'Global options:',
+      type: 'string',
+      default: process.env.NEON_API_KEY ?? '',
+    },
+    apiClient: {
+      hidden: true,
+      coerce: (v) => v as Api<unknown>,
+      default: null as unknown as Api<unknown>,
+    },
+    'context-file': {
+      describe: 'Context file',
+      type: 'string',
+      default: currentContextFile,
+    },
+  })
+  .middleware((args) => fillInArgs(args), true)
+  .help(false)
+  .group('help', 'Global options:')
+  .option('help', {
+    describe: 'Show help',
+    type: 'boolean',
+    default: false,
+  })
+  .alias('help', 'h')
+  .middleware(async (args) => {
+    if (
+      args.help ||
+      (args._.length === 1 &&
+        !NO_SUBCOMMANDS_VERBS.includes(args._[0] as string))
+    ) {
+      await showHelp(builder);
+    }
+  })
+  .middleware(ensureAuth)
+  .middleware(enrichFromContext as any)
+  .command(commands as any)
+  .strictCommands()
+  .option('analytics', {
+    describe: 'Manage analytics. Example: --no-analytics, --analytics false',
+    group: 'Global options:',
+    type: 'boolean',
+    default: true,
+  })
+  .middleware(analyticsMiddleware, true)
+  .group('version', 'Global options:')
+  .alias('version', 'v')
+  .completion()
+  .scriptName(basename(process.argv[1]) === 'neon' ? 'neon' : 'neonctl')
+  .epilog(
+    'For more information, visit https://neon.tech/docs/reference/neon-cli',
+  )
+  .wrap(null)
+  .fail(async (msg, err) => {
+    if (process.argv.some((arg) => arg === '--help' || arg === '-h')) {
+      await showHelp(builder);
+      process.exit(0);
+    }
+
+    if (isAxiosError(err)) {
+      if (err.code === 'ECONNABORTED') {
+        log.error('Request timed out');
+        sendError(err, 'REQUEST_TIMEOUT');
+      } else if (err.response?.status === 401) {
+        sendError(err, 'AUTH_FAILED');
+        log.error('Authentication failed, please run `neonctl auth`');
+      } else {
+        if (err.response?.data?.message) {
+          log.error(err.response?.data?.message);
+        }
+        log.debug(
+          'status: %d %s | path: %s',
+          err.response?.status,
+          err.response?.statusText,
+          err.request?.path,
+        );
+        sendError(err, 'API_ERROR');
+      }
+    } else {
+      sendError(err || new Error(msg), matchErrorCode(msg || err?.message));
+      log.error(msg || err?.message);
+    }
+    err?.stack && log.debug('Stack: %s', err.stack);
+    process.exit(1);
+  });
+
+(async () => {
+  const args = await builder.argv;
+  if (args._.length === 0 || args.help) {
+    await showHelp(builder);
+    process.exit(0);
+  }
+})();

package/src/log.ts

@@ -0,0 +1,16 @@
+import { format } from 'node:util';
+import { isDebug } from './env.js';
+
+export const log = {
+  debug: (...args: unknown[]) => {
+    if (isDebug()) {
+      process.stderr.write(`DEBUG: ${format(...args)}\n`);
+    }
+  },
+  info: (...args: unknown[]) => {
+    process.stderr.write(`INFO: ${format(...args)}\n`);
+  },
+  error: (...args: unknown[]) => {
+    process.stderr.write(`ERROR: ${format(...args)}\n`);
+  },
+};

package/src/parameters.gen.ts

@@ -0,0 +1,332 @@
+// FILE IS GENERATED, DO NOT EDIT
+
+export const projectCreateRequest = {
+  'project.settings.quota.active_time_seconds': {
+              type: "number",
+              description: "The total amount of wall-clock time allowed to be spent by the project's compute endpoints.\n",
+              demandOption: false,
+  },
+  'project.settings.quota.compute_time_seconds': {
+              type: "number",
+              description: "The total amount of CPU seconds allowed to be spent by the project's compute endpoints.\n",
+              demandOption: false,
+  },
+  'project.settings.quota.written_data_bytes': {
+              type: "number",
+              description: "Total amount of data written to all of a project's branches.\n",
+              demandOption: false,
+  },
+  'project.settings.quota.data_transfer_bytes': {
+              type: "number",
+              description: "Total amount of data transferred from all of a project's branches using the proxy.\n",
+              demandOption: false,
+  },
+  'project.settings.quota.logical_size_bytes': {
+              type: "number",
+              description: "Limit on the logical size of every project's branch.\n",
+              demandOption: false,
+  },
+  'project.settings.allowed_ips.ips': {
+              type: "array",
+              description: "A list of IP addresses that are allowed to connect to the endpoint.",
+              demandOption: false,
+  },
+  'project.settings.allowed_ips.primary_branch_only': {
+              type: "boolean",
+              description: "If true, the list will be applied only to the primary branch.",
+              demandOption: true,
+  },
+  'project.settings.enable_logical_replication': {
+              type: "boolean",
+              description: "Sets wal_level=logical for all compute endpoints in this project.\nAll active endpoints will be suspended.\nOnce enabled, logical replication cannot be disabled.\n",
+              demandOption: false,
+  },
+  'project.name': {
+              type: "string",
+              description: "The project name",
+              demandOption: false,
+  },
+  'project.branch.name': {
+              type: "string",
+              description: "The branch name. If not specified, the default branch name will be used.\n",
+              demandOption: false,
+  },
+  'project.branch.role_name': {
+              type: "string",
+              description: "The role name. If not specified, the default role name will be used.\n",
+              demandOption: false,
+  },
+  'project.branch.database_name': {
+              type: "string",
+              description: "The database name. If not specified, the default database name will be used.\n",
+              demandOption: false,
+  },
+  'project.provisioner': {
+              type: "string",
+              description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n",
+              demandOption: false,
+ choices: ["k8s-pod","k8s-neonvm"],
+  },
+  'project.region_id': {
+              type: "string",
+              description: "The region identifier. Refer to our [Regions](https://neon.tech/docs/introduction/regions) documentation for supported regions. Values are specified in this format: `aws-us-east-1`\n",
+              demandOption: false,
+  },
+  'project.default_endpoint_settings.suspend_timeout_seconds': {
+              type: "number",
+              description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the global default.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Auto-suspend configuration](https://neon.tech/docs/manage/endpoints#auto-suspend-configuration).\n",
+              demandOption: false,
+  },
+  'project.pg_version': {
+              type: "number",
+              description: "The major Postgres version number. Currently supported versions are `14`, `15`, and `16`.",
+              demandOption: false,
+  },
+  'project.store_passwords': {
+              type: "boolean",
+              description: "Whether or not passwords are stored for roles in the Neon project. Storing passwords facilitates access to Neon features that require authorization.\n",
+              demandOption: false,
+  },
+  'project.history_retention_seconds': {
+              type: "number",
+              description: "The number of seconds to retain the point-in-time restore (PITR) backup history for this project.\nThe default is 604800 seconds (7 days).\n",
+              demandOption: false,
+  },
+} as const;
+
+export const projectUpdateRequest = {
+  'project.settings.quota.active_time_seconds': {
+              type: "number",
+              description: "The total amount of wall-clock time allowed to be spent by the project's compute endpoints.\n",
+              demandOption: false,
+  },
+  'project.settings.quota.compute_time_seconds': {
+              type: "number",
+              description: "The total amount of CPU seconds allowed to be spent by the project's compute endpoints.\n",
+              demandOption: false,
+  },
+  'project.settings.quota.written_data_bytes': {
+              type: "number",
+              description: "Total amount of data written to all of a project's branches.\n",
+              demandOption: false,
+  },
+  'project.settings.quota.data_transfer_bytes': {
+              type: "number",
+              description: "Total amount of data transferred from all of a project's branches using the proxy.\n",
+              demandOption: false,
+  },
+  'project.settings.quota.logical_size_bytes': {
+              type: "number",
+              description: "Limit on the logical size of every project's branch.\n",
+              demandOption: false,
+  },
+  'project.settings.allowed_ips.ips': {
+              type: "array",
+              description: "A list of IP addresses that are allowed to connect to the endpoint.",
+              demandOption: false,
+  },
+  'project.settings.allowed_ips.primary_branch_only': {
+              type: "boolean",
+              description: "If true, the list will be applied only to the primary branch.",
+              demandOption: true,
+  },
+  'project.settings.enable_logical_replication': {
+              type: "boolean",
+              description: "Sets wal_level=logical for all compute endpoints in this project.\nAll active endpoints will be suspended.\nOnce enabled, logical replication cannot be disabled.\n",
+              demandOption: false,
+  },
+  'project.name': {
+              type: "string",
+              description: "The project name",
+              demandOption: false,
+  },
+  'project.default_endpoint_settings.suspend_timeout_seconds': {
+              type: "number",
+              description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the global default.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Auto-suspend configuration](https://neon.tech/docs/manage/endpoints#auto-suspend-configuration).\n",
+              demandOption: false,
+  },
+  'project.history_retention_seconds': {
+              type: "number",
+              description: "The number of seconds to retain the point-in-time restore (PITR) backup history for this project.\nThe default is 604800 seconds (7 days).\n",
+              demandOption: false,
+  },
+} as const;
+
+export const branchCreateRequest = {
+  'endpoints': {
+              type: "array",
+              description: undefined,
+              demandOption: false,
+  },
+  'branch.parent_id': {
+              type: "string",
+              description: "The `branch_id` of the parent branch. If omitted or empty, the branch will be created from the project's primary branch.\n",
+              demandOption: false,
+  },
+  'branch.name': {
+              type: "string",
+              description: "The branch name\n",
+              demandOption: false,
+  },
+  'branch.parent_lsn': {
+              type: "string",
+              description: "A Log Sequence Number (LSN) on the parent branch. The branch will be created with data from this LSN.\n",
+              demandOption: false,
+  },
+  'branch.parent_timestamp': {
+              type: "string",
+              description: "A timestamp identifying a point in time on the parent branch. The branch will be created with data starting from this point in time.\nThe timestamp must be provided in ISO 8601 format; for example: `2024-02-26T12:00:00Z`.\n",
+              demandOption: false,
+  },
+  'branch.protected': {
+              type: "boolean",
+              description: "Whether the branch is protected\n",
+              demandOption: false,
+  },
+} as const;
+
+export const branchCreateRequestEndpointOptions = {
+  'type': {
+              type: "string",
+              description: "The compute endpoint type. Either `read_write` or `read_only`.\nThe `read_only` compute endpoint type is not yet supported.\n",
+              demandOption: true,
+ choices: ["read_only","read_write"],
+  },
+  'provisioner': {
+              type: "string",
+              description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n",
+              demandOption: false,
+ choices: ["k8s-pod","k8s-neonvm"],
+  },
+  'suspend_timeout_seconds': {
+              type: "number",
+              description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the global default.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Auto-suspend configuration](https://neon.tech/docs/manage/endpoints#auto-suspend-configuration).\n",
+              demandOption: false,
+  },
+} as const;
+
+export const branchUpdateRequest = {
+  'branch.name': {
+              type: "string",
+              description: undefined,
+              demandOption: false,
+  },
+  'branch.protected': {
+              type: "boolean",
+              description: undefined,
+              demandOption: false,
+  },
+} as const;
+
+export const endpointCreateRequest = {
+  'endpoint.branch_id': {
+              type: "string",
+              description: "The ID of the branch the compute endpoint will be associated with\n",
+              demandOption: true,
+  },
+  'endpoint.region_id': {
+              type: "string",
+              description: "The region where the compute endpoint will be created. Only the project's `region_id` is permitted.\n",
+              demandOption: false,
+  },
+  'endpoint.type': {
+              type: "string",
+              description: "The compute endpoint type. Either `read_write` or `read_only`.\nThe `read_only` compute endpoint type is not yet supported.\n",
+              demandOption: true,
+ choices: ["read_only","read_write"],
+  },
+  'endpoint.provisioner': {
+              type: "string",
+              description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n",
+              demandOption: false,
+ choices: ["k8s-pod","k8s-neonvm"],
+  },
+  'endpoint.pooler_enabled': {
+              type: "boolean",
+              description: "Whether to enable connection pooling for the compute endpoint\n",
+              demandOption: false,
+  },
+  'endpoint.pooler_mode': {
+              type: "string",
+              description: "The connection pooler mode. Neon supports PgBouncer in `transaction` mode only.\n",
+              demandOption: false,
+ choices: ["transaction"],
+  },
+  'endpoint.disabled': {
+              type: "boolean",
+              description: "Whether to restrict connections to the compute endpoint.\nEnabling this option schedules a suspend compute operation.\nA disabled compute endpoint cannot be enabled by a connection or\nconsole action. However, the compute endpoint is periodically\nenabled by check_availability operations.\n",
+              demandOption: false,
+  },
+  'endpoint.passwordless_access': {
+              type: "boolean",
+              description: "NOT YET IMPLEMENTED. Whether to permit passwordless access to the compute endpoint.\n",
+              demandOption: false,
+  },
+  'endpoint.suspend_timeout_seconds': {
+              type: "number",
+              description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the global default.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Auto-suspend configuration](https://neon.tech/docs/manage/endpoints#auto-suspend-configuration).\n",
+              demandOption: false,
+  },
+} as const;
+
+export const endpointUpdateRequest = {
+  'endpoint.branch_id': {
+              type: "string",
+              description: "The destination branch ID. The destination branch must not have an exsiting read-write endpoint.\n",
+              demandOption: false,
+  },
+  'endpoint.provisioner': {
+              type: "string",
+              description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n",
+              demandOption: false,
+ choices: ["k8s-pod","k8s-neonvm"],
+  },
+  'endpoint.pooler_enabled': {
+              type: "boolean",
+              description: "Whether to enable connection pooling for the compute endpoint\n",
+              demandOption: false,
+  },
+  'endpoint.pooler_mode': {
+              type: "string",
+              description: "The connection pooler mode. Neon supports PgBouncer in `transaction` mode only.\n",
+              demandOption: false,
+ choices: ["transaction"],
+  },
+  'endpoint.disabled': {
+              type: "boolean",
+              description: "Whether to restrict connections to the compute endpoint.\nEnabling this option schedules a suspend compute operation.\nA disabled compute endpoint cannot be enabled by a connection or\nconsole action. However, the compute endpoint is periodically\nenabled by check_availability operations.\n",
+              demandOption: false,
+  },
+  'endpoint.passwordless_access': {
+              type: "boolean",
+              description: "NOT YET IMPLEMENTED. Whether to permit passwordless access to the compute endpoint.\n",
+              demandOption: false,
+  },
+  'endpoint.suspend_timeout_seconds': {
+              type: "number",
+              description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the global default.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Auto-suspend configuration](https://neon.tech/docs/manage/endpoints#auto-suspend-configuration).\n",
+              demandOption: false,
+  },
+} as const;
+
+export const databaseCreateRequest = {
+  'database.name': {
+              type: "string",
+              description: "The name of the datbase\n",
+              demandOption: true,
+  },
+  'database.owner_name': {
+              type: "string",
+              description: "The name of the role that owns the database\n",
+              demandOption: true,
+  },
+} as const;
+
+export const roleCreateRequest = {
+  'role.name': {
+              type: "string",
+              description: "The role name. Cannot exceed 63 bytes in length.\n",
+              demandOption: true,
+  },
+} as const;
+

package/src/pkg.ts

@@ -0,0 +1,9 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export default JSON.parse(
+  readFileSync(
+    fileURLToPath(new URL('./package.json', import.meta.url)),
+    'utf-8',
+  ),
+);

package/src/test_utils/mock_server.ts

@@ -0,0 +1,27 @@
+import emocks from 'emocks';
+import express from 'express';
+import { Server } from 'node:http';
+import { AddressInfo } from 'node:net';
+import { join } from 'node:path';
+import { log } from '../log';
+
+export const runMockServer = async (mockDir: string) =>
+  new Promise<Server>((resolve) => {
+    const app = express();
+    app.use(express.json());
+    app.use(
+      '/',
+      emocks(join(process.cwd(), 'mocks', mockDir), {
+        '404': (req, res) => res.status(404).send({ message: 'Not Found' }),
+      }),
+    );
+
+    const server = app.listen(0);
+    server.on('listening', () => {
+      resolve(server);
+      log.info(
+        'Mock server listening at %d',
+        (server.address() as AddressInfo).port,
+      );
+    });
+  });

package/src/test_utils/oauth_server.ts

@@ -0,0 +1,10 @@
+import { log } from '../log';
+import { OAuth2Server } from 'oauth2-mock-server';
+
+export const startOauthServer = async () => {
+  const server = new OAuth2Server();
+  await server.issuer.keys.generate('RS256');
+  await server.start(0, 'localhost');
+  log.info('Started OAuth server');
+  return server;
+};