feat(sandbox): add sandbox module

.env.example

@@ -0,0 +1,33 @@
+# Copy this file to .env in the project root before running sandbox examples
+# or sandbox integration tests.
+
+# Sandbox API key auth.
+QINIU_SANDBOX_API_KEY=
+
+# Optional custom endpoint.
+QINIU_SANDBOX_ENDPOINT=
+
+# Optional template alias or ID. Defaults to base.
+QINIU_SANDBOX_TEMPLATE=base
+
+# Required only for injection-rule and Kodo resource examples.
+QINIU_SANDBOX_ACCESS_KEY=
+QINIU_SANDBOX_SECRET_KEY=
+
+# Optional Git remote examples.
+GIT_REPO_URL=
+GIT_USERNAME=
+GIT_PASSWORD=
+
+# Optional Git repository resource example.
+GITHUB_TOKEN=
+QINIU_SANDBOX_GIT_MOUNT_PATH=/workspace/repo
+
+# Optional Kodo resource example.
+QINIU_SANDBOX_KODO_BUCKET=
+QINIU_SANDBOX_KODO_MOUNT_PATH=/workspace/kodo
+QINIU_SANDBOX_KODO_PREFIX=
+
+# Optional request injection examples.
+QINIU_SANDBOX_HTTP_INJECTION_TOKEN=real_token
+QINIU_SANDBOX_OPENAI_API_KEY=

.github/workflows/ci-test.yml

@@ -24,7 +24,12 @@ jobs:
       - name: Run cases
         run: |
           npm run check-type
-          nyc --reporter=lcov npm test
+          nyc --reporter=lcov --include 'qiniu/sandbox/**/*.js' npm run test:sandbox
+          if [ -n "$QINIU_ACCESS_KEY" ] && [ -n "$QINIU_SECRET_KEY" ] && [ -n "$QINIU_TEST_BUCKET" ] && [ -n "$QINIU_TEST_DOMAIN" ]; then
+            nyc --no-clean --reporter=lcov npm test
+          else
+            npm test
+          fi
         env:
           QINIU_ACCESS_KEY: ${{ secrets.QINIU_ACCESS_KEY }}
           QINIU_SECRET_KEY: ${{ secrets.QINIU_SECRET_KEY }}

.gitignore

@@ -27,3 +27,4 @@ coverage/
 yarn.lock
 
 .claude/settings.local.json
+.env

examples/sandbox_common.js

@@ -0,0 +1,135 @@
+const fs = require('fs');
+const path = require('path');
+
+const qiniu = require('../index');
+const { shellQuote } = require('../qiniu/sandbox/util');
+
+function loadDotEnvIfPresent () {
+    const files = [
+        path.join(process.cwd(), '.env')
+    ];
+
+    files.forEach(filepath => {
+        if (!fs.existsSync(filepath)) {
+            return;
+        }
+
+        fs.readFileSync(filepath, 'utf8')
+            .split(/\r?\n/)
+            .forEach(line => {
+                line = line.trim();
+                if (!line || line[0] === '#') {
+                    return;
+                }
+                const index = line.indexOf('=');
+                if (index < 0) {
+                    return;
+                }
+                const key = line.slice(0, index).trim();
+                let value = line.slice(index + 1).trim();
+                if (
+                    (value[0] === '"' && value[value.length - 1] === '"') ||
+                    (value[0] === '\'' && value[value.length - 1] === '\'')
+                ) {
+                    value = value.slice(1, -1);
+                }
+                if (process.env[key] === undefined) {
+                    process.env[key] = value;
+                }
+            });
+    });
+}
+
+function env (key, fallback) {
+    return process.env[key] || fallback;
+}
+
+function requiredEnv (key) {
+    if (process.env[key]) {
+        return process.env[key];
+    }
+    throw new Error(`Please set ${key}`);
+}
+
+function sandboxEndpoint () {
+    return env('QINIU_SANDBOX_ENDPOINT');
+}
+
+function sandboxApiKey () {
+    return requiredEnv('QINIU_SANDBOX_API_KEY');
+}
+
+function sandboxTemplate () {
+    return env('QINIU_SANDBOX_TEMPLATE', 'base');
+}
+
+function sandboxClient (options) {
+    options = Object.assign({
+        endpoint: sandboxEndpoint(),
+        apiKey: sandboxApiKey()
+    }, options || {});
+    return new qiniu.sandbox.SandboxClient(options);
+}
+
+function sandboxMac () {
+    const accessKey = requiredEnv('QINIU_SANDBOX_ACCESS_KEY');
+    const secretKey = requiredEnv('QINIU_SANDBOX_SECRET_KEY');
+    return new qiniu.auth.digest.Mac(accessKey, secretKey);
+}
+
+function createSandboxAndWait (options, pollOptions) {
+    const client = options && options.client ? options.client : sandboxClient();
+    const params = Object.assign({
+        client,
+        template: sandboxTemplate(),
+        timeout: 300
+    }, options || {});
+
+    return qiniu.sandbox.Sandbox.create(params).then(sandbox => {
+        console.log('Sandbox created:', sandbox.sandboxId);
+        return sandbox.waitForReady(Object.assign({
+            interval: 3000,
+            timeout: 180000
+        }, pollOptions || {})).then(info => {
+            console.log('Sandbox ready:', sandbox.sandboxId, info.state || '');
+            return sandbox;
+        });
+    });
+}
+
+function cleanupSandbox (sandbox) {
+    if (!sandbox) {
+        return Promise.resolve();
+    }
+    return sandbox.kill()
+        .then(() => {
+            console.log('Sandbox killed:', sandbox.sandboxId);
+        }, err => {
+            console.log('Failed to kill sandbox:', sandbox.sandboxId, err.message);
+        });
+}
+
+function runExample (fn) {
+    loadDotEnvIfPresent();
+    Promise.resolve()
+        .then(fn)
+        .catch(err => {
+            console.error(err && err.stack ? err.stack : err);
+            process.exitCode = 1;
+        });
+}
+
+module.exports = {
+    qiniu,
+    shellQuote,
+    env,
+    requiredEnv,
+    sandboxEndpoint,
+    sandboxApiKey,
+    sandboxTemplate,
+    sandboxClient,
+    sandboxMac,
+    createSandboxAndWait,
+    cleanupSandbox,
+    runExample
+};

examples/sandbox_create.js

@@ -0,0 +1,25 @@
+const {
+    qiniu,
+    sandboxClient,
+    sandboxTemplate,
+    cleanupSandbox,
+    runExample
+} = require('./sandbox_common');
+
+runExample(() => {
+    const client = sandboxClient();
+    let sandbox;
+
+    return qiniu.sandbox.Sandbox.create(sandboxTemplate(), {
+        client,
+        timeout: 300,
+        metadata: {
+            example: 'sandbox_create'
+        }
+    }).then(created => {
+        sandbox = created;
+        console.log('Sandbox created:', sandbox.sandboxId);
+        console.log('Template:', sandbox.info.templateID || sandbox.info.template_id || sandboxTemplate());
+        return cleanupSandbox(sandbox);
+    });
+});

examples/sandbox_envd.js

@@ -0,0 +1,68 @@
+const {
+    shellQuote,
+    createSandboxAndWait,
+    cleanupSandbox,
+    runExample
+} = require('./sandbox_common');
+
+runExample(() => {
+    let sandbox;
+    const workdir = '/tmp/qiniu-nodejs-sdk-envd';
+    const filePath = `${workdir}/hello.txt`;
+
+    return createSandboxAndWait({
+        metadata: {
+            example: 'sandbox_envd'
+        }
+    }).then(created => {
+        sandbox = created;
+        console.log('Public host for port 8080:', sandbox.getHost(8080));
+        return sandbox.commands.run(`mkdir -p ${shellQuote(workdir)}`);
+    }).then(result => {
+        console.log('mkdir exit:', result.exitCode);
+        return sandbox.files.write(filePath, 'Hello from Qiniu Node.js SDK\n');
+    }).then(entry => {
+        console.log('Wrote:', entry.path || entry);
+        return sandbox.files.readText(filePath);
+    }).then(text => {
+        console.log('ReadText:', JSON.stringify(text));
+        return sandbox.files.writeFiles([
+            { path: `${workdir}/batch-a.txt`, data: 'file A content\n' },
+            { path: `${workdir}/batch-b.txt`, data: 'file B content\n' }
+        ]);
+    }).then(entries => {
+        console.log('WriteFiles:', entries.map(item => item.path));
+        return sandbox.files.read(`${workdir}/batch-a.txt`, { format: 'bytes' });
+    }).then(bytes => {
+        console.log('Read bytes:', bytes.length);
+        return sandbox.files.list(workdir);
+    }).then(entries => {
+        console.log('List:', entries.map(item => `${item.type}:${item.name}`));
+        return sandbox.files.exists(filePath);
+    }).then(exists => {
+        console.log('Exists:', exists);
+        return sandbox.files.getInfo(filePath);
+    }).then(info => {
+        console.log('GetInfo:', info.name, info.size);
+        return sandbox.files.rename(`${workdir}/batch-b.txt`, `${workdir}/batch-b-renamed.txt`);
+    }).then(info => {
+        console.log('Renamed to:', info.path);
+        return sandbox.files.remove(`${workdir}/batch-b-renamed.txt`);
+    }).then(() => {
+        console.log('Removed renamed file');
+        return sandbox.commands.run('echo $MY_VAR && pwd', {
+            cwd: workdir,
+            envs: {
+                MY_VAR: 'sandbox-value'
+            }
+        });
+    }).then(result => {
+        console.log('Command exit:', result.exitCode);
+        console.log('stdout:\n' + result.stdout);
+        return cleanupSandbox(sandbox);
+    }, err => {
+        return cleanupSandbox(sandbox).then(() => {
+            throw err;
+        });
+    });
+});

examples/sandbox_filesystem_encoding.js

@@ -0,0 +1,34 @@
+const {
+    createSandboxAndWait,
+    cleanupSandbox,
+    runExample
+} = require('./sandbox_common');
+
+runExample(() => {
+    let sandbox;
+    const filePath = '/tmp/qiniu-nodejs-sdk-encoding.txt';
+
+    return createSandboxAndWait({
+        metadata: {
+            example: 'sandbox_filesystem_encoding'
+        }
+    }).then(created => {
+        sandbox = created;
+        return sandbox.files.write(filePath, 'hello with octet-stream and gzip\n', {
+            useOctetStream: true,
+            gzip: true
+        });
+    }).then(entry => {
+        console.log('Wrote:', entry.path || entry);
+        return sandbox.files.read(filePath, {
+            gzip: true
+        });
+    }).then(text => {
+        console.log('Read:', JSON.stringify(text));
+        return cleanupSandbox(sandbox);
+    }, err => {
+        return cleanupSandbox(sandbox).then(() => {
+            throw err;
+        });
+    });
+});