neonctl 1.29.1 → 1.29.4

package/analytics.js

@@ -0,0 +1,78 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Analytics } from '@segment/analytics-node';
+import { isAxiosError } from 'axios';
+import { CREDENTIALS_FILE } from './config.js';
+import { isCi } from './env.js';
+import { log } from './log.js';
+import pkg from './pkg.js';
+import { getApiClient } from './api.js';
+const WRITE_KEY = '3SQXn5ejjXWLEJ8xU2PRYhAotLtTaeeV';
+let client;
+let userId = '';
+export const analyticsMiddleware = async (args) => {
+    if (!args.analytics) {
+        return;
+    }
+    try {
+        const credentialsPath = join(args.configDir, CREDENTIALS_FILE);
+        const credentials = readFileSync(credentialsPath, { encoding: 'utf-8' });
+        userId = JSON.parse(credentials).user_id;
+    }
+    catch (err) {
+        log.debug('Failed to read credentials file', err);
+    }
+    try {
+        if (!userId && args.apiKey) {
+            const apiClient = getApiClient({
+                apiKey: args.apiKey,
+                apiHost: args.apiHost,
+            });
+            const resp = await apiClient?.getCurrentUserInfo?.();
+            userId = resp?.data?.id;
+        }
+    }
+    catch (err) {
+        log.debug('Failed to get user id from api', err);
+    }
+    client = new Analytics({
+        writeKey: WRITE_KEY,
+        host: 'https://track.neon.tech',
+    });
+    client.identify({
+        userId: userId?.toString() ?? 'anonymous',
+    });
+    client.track({
+        userId: userId ?? 'anonymous',
+        event: 'CLI Started',
+        properties: {
+            version: pkg.version,
+            command: args._.join(' '),
+            flags: {
+                output: args.output,
+            },
+            ci: isCi(),
+        },
+    });
+    log.debug('Flushing CLI started event with userId: %s', userId);
+    await client.closeAndFlush();
+    log.debug('Flushed CLI started event with userId: %s', userId);
+};
+export const sendError = (err, errCode) => {
+    if (!client) {
+        return;
+    }
+    const axiosError = isAxiosError(err) ? err : undefined;
+    client.track({
+        event: 'CLI Error',
+        userId: userId ?? 'anonymous',
+        properties: {
+            message: err.message,
+            stack: err.stack,
+            errCode,
+            statusCode: axiosError?.response?.status,
+        },
+    });
+    client.closeAndFlush();
+    log.debug('Sent CLI error event: %s', errCode);
+};

package/api.js

@@ -0,0 +1,35 @@
+import { createApiClient } from '@neondatabase/api-client';
+import { isAxiosError } from 'axios';
+import { log } from './log.js';
+import pkg from './pkg.js';
+export const getApiClient = ({ apiKey, apiHost }) => createApiClient({
+    apiKey,
+    baseURL: apiHost,
+    timeout: 60000,
+    headers: {
+        'User-Agent': `neonctl v${pkg.version}`,
+    },
+});
+const RETRY_COUNT = 5;
+const RETRY_DELAY = 3000;
+export const retryOnLock = async (fn) => {
+    let attempt = 0;
+    let errOut;
+    while (attempt < RETRY_COUNT) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            errOut = err;
+            if (isAxiosError(err) && err.response?.status === 423) {
+                attempt++;
+                log.info(`Resource is locked. Waiting ${RETRY_DELAY}ms before retrying...`);
+                await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY));
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    throw errOut;
+};

package/auth.js

@@ -0,0 +1,101 @@
+import { custom, generators, Issuer } from 'openid-client';
+import { createServer } from 'node:http';
+import { createReadStream } from 'node:fs';
+import { join } from 'node:path';
+import open from 'open';
+import { log } from './log.js';
+import { fileURLToPath } from 'node:url';
+// oauth server timeouts
+const SERVER_TIMEOUT = 10000;
+// where to wait for incoming redirect request from oauth server to arrive
+const REDIRECT_URI = (port) => `http://127.0.0.1:${port}/callback`;
+// These scopes cannot be cancelled, they are always needed.
+const ALWAYS_PRESENT_SCOPES = ['openid', 'offline', 'offline_access'];
+const NEONCTL_SCOPES = [
+    ...ALWAYS_PRESENT_SCOPES,
+    'urn:neoncloud:projects:create',
+    'urn:neoncloud:projects:read',
+    'urn:neoncloud:projects:update',
+    'urn:neoncloud:projects:delete',
+];
+export const defaultClientID = 'neonctl';
+custom.setHttpOptionsDefaults({
+    timeout: SERVER_TIMEOUT,
+});
+export const refreshToken = async ({ oauthHost, clientId }, tokenSet) => {
+    log.debug('Discovering oauth server');
+    const issuer = await Issuer.discover(oauthHost);
+    const neonOAuthClient = new issuer.Client({
+        token_endpoint_auth_method: 'none',
+        client_id: clientId,
+        response_types: ['code'],
+    });
+    return await neonOAuthClient.refresh(tokenSet);
+};
+export const auth = async ({ oauthHost, clientId }) => {
+    log.debug('Discovering oauth server');
+    const issuer = await Issuer.discover(oauthHost);
+    //
+    // Start HTTP server and wait till /callback is hit
+    //
+    const server = createServer();
+    server.listen(0, '127.0.0.1', function () {
+        log.debug(`Listening on port ${this.address().port}`);
+    });
+    await new Promise((resolve) => server.once('listening', resolve));
+    const listen_port = server.address().port;
+    const neonOAuthClient = new issuer.Client({
+        token_endpoint_auth_method: 'none',
+        client_id: clientId,
+        redirect_uris: [REDIRECT_URI(listen_port)],
+        response_types: ['code'],
+    });
+    // https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.1.8
+    const state = generators.state();
+    // we store the code_verifier in memory
+    const codeVerifier = generators.codeVerifier();
+    const codeChallenge = generators.codeChallenge(codeVerifier);
+    return new Promise((resolve) => {
+        server.on('request', async (request, response) => {
+            //
+            // Wait for callback and follow oauth flow.
+            //
+            if (!request.url?.startsWith('/callback')) {
+                response.writeHead(404);
+                response.end();
+                return;
+            }
+            // process the CORS preflight OPTIONS request
+            if (request.method === 'OPTIONS') {
+                response.writeHead(200, {
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Methods': 'GET, POST',
+                    'Access-Control-Allow-Headers': 'Content-Type',
+                });
+                response.end();
+                return;
+            }
+            log.debug(`Callback received: ${request.url}`);
+            const params = neonOAuthClient.callbackParams(request);
+            const tokenSet = await neonOAuthClient.callback(REDIRECT_URI(listen_port), params, {
+                code_verifier: codeVerifier,
+                state,
+            });
+            response.writeHead(200, { 'Content-Type': 'text/html' });
+            createReadStream(join(fileURLToPath(new URL('.', import.meta.url)), './callback.html')).pipe(response);
+            resolve(tokenSet);
+            server.close();
+        });
+        //
+        // Open browser to let user authenticate
+        //
+        const scopes = clientId == defaultClientID ? NEONCTL_SCOPES : ALWAYS_PRESENT_SCOPES;
+        const authUrl = neonOAuthClient.authorizationUrl({
+            scope: scopes.join(' '),
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+        });
+        open(authUrl);
+    });
+};

package/{src/cli.ts → cli.js}

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
-
 import './index.js';

package/commands/auth.js

@@ -0,0 +1,102 @@
+import { join } from 'node:path';
+import { writeFileSync, existsSync, readFileSync } from 'node:fs';
+import { TokenSet } from 'openid-client';
+import { auth, refreshToken } from '../auth.js';
+import { log } from '../log.js';
+import { getApiClient } from '../api.js';
+import { isCi } from '../env.js';
+import { CREDENTIALS_FILE } from '../config.js';
+export const command = 'auth';
+export const aliases = ['login'];
+export const describe = 'Authenticate';
+export const builder = (yargs) => yargs.option('context-file', {
+    hidden: true,
+});
+export const handler = async (args) => {
+    await authFlow(args);
+};
+export const authFlow = async ({ configDir, oauthHost, clientId, apiHost, forceAuth, }) => {
+    if (!forceAuth && isCi()) {
+        throw new Error('Cannot run interactive auth in CI');
+    }
+    const tokenSet = await auth({
+        oauthHost: oauthHost,
+        clientId: clientId,
+    });
+    const credentialsPath = join(configDir, CREDENTIALS_FILE);
+    await preserveCredentials(credentialsPath, tokenSet, getApiClient({
+        apiKey: tokenSet.access_token || '',
+        apiHost,
+    }));
+    log.info(`Saved credentials to ${credentialsPath}`);
+    log.info('Auth complete');
+    return tokenSet.access_token || '';
+};
+const preserveCredentials = async (path, credentials, apiClient) => {
+    const { data: { id }, } = await apiClient.getCurrentUserInfo();
+    const contents = JSON.stringify({
+        ...credentials,
+        user_id: id,
+    });
+    // correctly sets needed permissions for the credentials file
+    writeFileSync(path, contents, {
+        mode: 0o700,
+    });
+};
+export const ensureAuth = async (props) => {
+    if (props._.length === 0 || props.help) {
+        return;
+    }
+    if (props.apiKey || props._[0] === 'auth') {
+        props.apiClient = getApiClient({
+            apiKey: props.apiKey,
+            apiHost: props.apiHost,
+        });
+        return;
+    }
+    const credentialsPath = join(props.configDir, CREDENTIALS_FILE);
+    if (existsSync(credentialsPath)) {
+        try {
+            const tokenSetContents = await JSON.parse(readFileSync(credentialsPath, 'utf8'));
+            const tokenSet = new TokenSet(tokenSetContents);
+            if (tokenSet.expired()) {
+                log.debug('using refresh token to update access token');
+                const refreshedTokenSet = await refreshToken({
+                    oauthHost: props.oauthHost,
+                    clientId: props.clientId,
+                }, tokenSet).catch((e) => {
+                    log.error('failed to refresh token\n%s', e?.message);
+                    process.exit(1);
+                });
+                props.apiKey = refreshedTokenSet.access_token || 'UNKNOWN';
+                props.apiClient = getApiClient({
+                    apiKey: props.apiKey,
+                    apiHost: props.apiHost,
+                });
+                await preserveCredentials(credentialsPath, refreshedTokenSet, props.apiClient);
+                return;
+            }
+            const token = tokenSet.access_token || 'UNKNOWN';
+            props.apiKey = token;
+            props.apiClient = getApiClient({
+                apiKey: props.apiKey,
+                apiHost: props.apiHost,
+            });
+            return;
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT') {
+                // not a "file does not exist" error
+                throw e;
+            }
+            props.apiKey = await authFlow(props);
+        }
+    }
+    else {
+        props.apiKey = await authFlow(props);
+    }
+    props.apiClient = getApiClient({
+        apiKey: props.apiKey,
+        apiHost: props.apiHost,
+    });
+};

package/commands/auth.test.js

@@ -0,0 +1,42 @@
+import axios from 'axios';
+import { beforeAll, describe, test, jest, afterAll, expect, } from '@jest/globals';
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { startOauthServer } from '../test_utils/oauth_server';
+import { runMockServer } from '../test_utils/mock_server';
+jest.unstable_mockModule('open', () => ({
+    __esModule: true,
+    default: jest.fn((url) => {
+        axios.get(url);
+    }),
+}));
+// "open" module should be imported after mocking
+const authModule = await import('./auth');
+describe('auth', () => {
+    let configDir = '';
+    let oauthServer;
+    let mockServer;
+    beforeAll(async () => {
+        configDir = mkdtempSync('test-config');
+        oauthServer = await startOauthServer();
+        mockServer = await runMockServer('main');
+    });
+    afterAll(async () => {
+        rmSync(configDir, { recursive: true });
+        await oauthServer.stop();
+        await new Promise((resolve) => mockServer.close(resolve));
+    });
+    test('should auth', async () => {
+        await authModule.authFlow({
+            _: ['auth'],
+            apiHost: `http://localhost:${mockServer.address().port}`,
+            clientId: 'test-client-id',
+            configDir,
+            forceAuth: true,
+            oauthHost: `http://localhost:${oauthServer.address().port}`,
+        });
+        const credentials = JSON.parse(readFileSync(`${configDir}/credentials.json`, 'utf-8'));
+        expect(credentials.access_token).toEqual(expect.any(String));
+        expect(credentials.refresh_token).toEqual(expect.any(String));
+        expect(credentials.user_id).toEqual(expect.any(String));
+    });
+});

package/commands/branches.js

@@ -0,0 +1,303 @@
+import { EndpointType } from '@neondatabase/api-client';
+import { writer } from '../writer.js';
+import { branchCreateRequest } from '../parameters.gen.js';
+import { retryOnLock } from '../api.js';
+import { branchIdFromProps, branchIdResolve, fillSingleProject, } from '../utils/enrichers.js';
+import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp, } from '../utils/formats.js';
+import { psql } from '../utils/psql.js';
+import { parsePointInTime } from '../utils/point_in_time.js';
+import { log } from '../log.js';
+const BRANCH_FIELDS = [
+    'id',
+    'name',
+    'primary',
+    'created_at',
+    'updated_at',
+];
+const BRANCH_FIELDS_RESET = [
+    'id',
+    'name',
+    'primary',
+    'created_at',
+    'last_reset_at',
+];
+export const command = 'branches';
+export const describe = 'Manage branches';
+export const aliases = ['branch'];
+export const builder = (argv) => argv
+    .usage('$0 branches <sub-command> [options]')
+    .options({
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+})
+    .middleware(fillSingleProject)
+    .command('list', 'List branches', (yargs) => yargs, async (args) => await list(args))
+    .command('create', 'Create a branch', (yargs) => yargs.options({
+    name: branchCreateRequest['branch.name'],
+    parent: {
+        describe: 'Parent branch name or id or timestamp or LSN. Defaults to the primary branch',
+        type: 'string',
+    },
+    compute: {
+        describe: 'Create a branch with or without a compute. By default branch is created with a read-write compute. To create a branch without compute use --no-compute',
+        type: 'boolean',
+        default: true,
+    },
+    type: {
+        describe: 'Type of compute to add',
+        type: 'string',
+        implies: 'compute',
+        default: EndpointType.ReadWrite,
+        choices: Object.values(EndpointType),
+    },
+    'suspend-timeout': {
+        describe: '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 maximum value is `604800` seconds (1 week).',
+        type: 'number',
+        implies: 'compute',
+        default: 0,
+    },
+    psql: {
+        type: 'boolean',
+        describe: 'Connect to a new branch via psql',
+        default: false,
+    },
+}), async (args) => await create(args))
+    .command('reset <id|name>', 'Reset a branch', (yargs) => yargs.options({
+    parent: {
+        describe: 'Reset to a parent branch',
+        type: 'boolean',
+        default: false,
+    },
+    'preserve-under-name': {
+        describe: 'Name under which to preserve the old branch',
+    },
+}), async (args) => await reset(args))
+    .command('restore <target-id|name> <source>[@(timestamp|lsn)]', 'Restores a branch to a specific point in time\n<source> can be: ^self, ^parent, or <source-branch-id|name>', (yargs) => yargs
+    // we want to show meaningful help for the command
+    // but it makes yargs to fail on parsing the command
+    // so we need to fill in the missing args manually
+    .middleware((args) => {
+    args.id = args.targetId;
+    args.pointInTime = args['source@(timestamp'];
+})
+    .usage('$0 branches restore <target-id|name> <source>[@(timestamp|lsn)]')
+    .options({
+    'preserve-under-name': {
+        describe: 'Name under which to preserve the old branch',
+    },
+})
+    .example([
+    [
+        '$0 branches restore main br-source-branch-123456',
+        'Restores main to the head of the branch with id br-source-branch-123456',
+    ],
+    [
+        '$0 branches restore main source@2021-01-01T00:00:00Z',
+        'Restores main to the timestamp 2021-01-01T00:00:00Z of the source branch',
+    ],
+    [
+        '$0 branches restore my-branch ^self@0/123456',
+        'Restores my-branch to the LSN 0/123456 from its own history',
+    ],
+    [
+        '$0 branches restore my-branch ^parent',
+        'Restore my-branch to the head of its parent branch',
+    ],
+]), async (args) => await restore(args))
+    .command('rename <id|name> <new-name>', 'Rename a branch', (yargs) => yargs, async (args) => await rename(args))
+    .command('set-primary <id|name>', 'Set a branch as primary', (yargs) => yargs, async (args) => await setPrimary(args))
+    .command('add-compute <id|name>', 'Add a compute to a branch', (yargs) => yargs.options({
+    type: {
+        type: 'string',
+        choices: Object.values(EndpointType),
+        describe: 'Type of compute to add',
+        default: EndpointType.ReadOnly,
+    },
+}), async (args) => await addCompute(args))
+    .command('delete <id|name>', 'Delete a branch', (yargs) => yargs, async (args) => await deleteBranch(args))
+    .command('get <id|name>', 'Get a branch', (yargs) => yargs, async (args) => await get(args));
+export const handler = (args) => {
+    return args;
+};
+const list = async (props) => {
+    const { data } = await props.apiClient.listProjectBranches(props.projectId);
+    writer(props).end(data.branches, {
+        fields: BRANCH_FIELDS,
+    });
+};
+const create = async (props) => {
+    const parentProps = await (() => {
+        if (!props.parent) {
+            return props.apiClient
+                .listProjectBranches(props.projectId)
+                .then(({ data }) => {
+                const branch = data.branches.find((b) => b.primary);
+                if (!branch) {
+                    throw new Error('No primary branch found');
+                }
+                return { parent_id: branch.id };
+            });
+        }
+        if (looksLikeLSN(props.parent)) {
+            return { parent_lsn: props.parent };
+        }
+        if (looksLikeTimestamp(props.parent)) {
+            return { parent_timestamp: props.parent };
+        }
+        if (looksLikeBranchId(props.parent)) {
+            return { parent_id: props.parent };
+        }
+        return props.apiClient
+            .listProjectBranches(props.projectId)
+            .then(({ data }) => {
+            const branch = data.branches.find((b) => b.name === props.parent);
+            if (!branch) {
+                throw new Error(`Branch ${props.parent} not found`);
+            }
+            return { parent_id: branch.id };
+        });
+    })();
+    const { data } = await retryOnLock(() => props.apiClient.createProjectBranch(props.projectId, {
+        branch: {
+            name: props.name,
+            ...parentProps,
+        },
+        endpoints: props.compute
+            ? [
+                {
+                    type: props.type,
+                    suspend_timeout_seconds: props.suspendTimeout === 0 ? undefined : props.suspendTimeout,
+                },
+            ]
+            : [],
+    }));
+    const out = writer(props);
+    out.write(data.branch, {
+        fields: BRANCH_FIELDS,
+        title: 'branch',
+    });
+    if (data.endpoints?.length > 0) {
+        out.write(data.endpoints, {
+            fields: ['id', 'created_at'],
+            title: 'endpoints',
+        });
+    }
+    if (data.connection_uris && data.connection_uris?.length > 0) {
+        out.write(data.connection_uris, {
+            fields: ['connection_uri'],
+            title: 'connection_uris',
+        });
+    }
+    out.end();
+    if (props.psql) {
+        if (!data.connection_uris || !data.connection_uris?.length) {
+            throw new Error(`Branch ${data.branch.id} doesn't have a connection uri`);
+        }
+        const connection_uri = data.connection_uris[0].connection_uri;
+        const psqlArgs = props['--'];
+        await psql(connection_uri, psqlArgs);
+    }
+};
+const rename = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await retryOnLock(() => props.apiClient.updateProjectBranch(props.projectId, branchId, {
+        branch: {
+            name: props.newName,
+        },
+    }));
+    writer(props).end(data.branch, {
+        fields: BRANCH_FIELDS,
+    });
+};
+const setPrimary = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await retryOnLock(() => props.apiClient.setPrimaryProjectBranch(props.projectId, branchId));
+    writer(props).end(data.branch, {
+        fields: BRANCH_FIELDS,
+    });
+};
+const deleteBranch = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await retryOnLock(() => props.apiClient.deleteProjectBranch(props.projectId, branchId));
+    writer(props).end(data.branch, {
+        fields: BRANCH_FIELDS,
+    });
+};
+const get = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await props.apiClient.getProjectBranch(props.projectId, branchId);
+    writer(props).end(data.branch, {
+        fields: BRANCH_FIELDS,
+    });
+};
+const addCompute = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await retryOnLock(() => props.apiClient.createProjectEndpoint(props.projectId, {
+        endpoint: {
+            branch_id: branchId,
+            type: props.type,
+        },
+    }));
+    writer(props).end(data.endpoint, {
+        fields: ['id', 'host'],
+    });
+};
+const reset = async (props) => {
+    if (!props.parent) {
+        throw new Error('Only resetting to parent is supported for now');
+    }
+    const branchId = await branchIdFromProps(props);
+    const { data: { branch: { parent_id }, }, } = await props.apiClient.getProjectBranch(props.projectId, branchId);
+    if (!parent_id) {
+        throw new Error('Branch has no parent');
+    }
+    const { data } = await retryOnLock(() => props.apiClient.restoreProjectBranch(props.projectId, branchId, {
+        source_branch_id: parent_id,
+        preserve_under_name: props.preserveUnderName || undefined,
+    }));
+    const resultBranch = data.branch;
+    writer(props).end(resultBranch, {
+        // need to reset types until we expose reset api
+        fields: BRANCH_FIELDS_RESET,
+    });
+};
+const restore = async (props) => {
+    const targetBranchId = await branchIdResolve({
+        branch: props.id,
+        projectId: props.projectId,
+        apiClient: props.apiClient,
+    });
+    const pointInTime = await parsePointInTime({
+        pointInTime: props.pointInTime,
+        targetBranchId,
+        projectId: props.projectId,
+        api: props.apiClient,
+    });
+    log.info(`Restoring branch ${targetBranchId} to the branch ${pointInTime.branchId} ${(pointInTime.tag === 'lsn' && 'LSN ' + pointInTime.lsn) ||
+        (pointInTime.tag === 'timestamp' &&
+            'timestamp ' + pointInTime.timestamp) ||
+        'head'}`);
+    const { data } = await retryOnLock(() => props.apiClient.restoreProjectBranch(props.projectId, targetBranchId, {
+        source_branch_id: pointInTime.branchId,
+        preserve_under_name: props.preserveUnderName || undefined,
+        ...(pointInTime.tag === 'lsn' && { source_lsn: pointInTime.lsn }),
+        ...(pointInTime.tag === 'timestamp' && {
+            source_timestamp: pointInTime.timestamp,
+        }),
+    }));
+    const branch = data.branch;
+    const writeInst = writer(props).write(branch, {
+        title: 'Restored branch',
+        fields: ['id', 'name', 'last_reset_at'],
+    });
+    if (props.preserveUnderName && branch.parent_id) {
+        const { data } = await props.apiClient.getProjectBranch(props.projectId, branch.parent_id);
+        writeInst.write(data.branch, {
+            title: 'Backup branch',
+            fields: ['id', 'name'],
+        });
+    }
+    writeInst.end();
+};