[ { "path": ".github/CODEOWNERS", "content": "# CODEOWNERS for OpenSandbox\n# Rules are evaluated top-to-bottom; the last matching pattern wins.\n\n# Default owners (fallback for files not matched by specific rules)\n* @jwx0925 @hittyt @hellomypastor @Pangjiping @ninan-nn\n\n# Control plane (server)\n/server/ @Pangjiping @hittyt @jwx0925 @Generalwin @ninan-nn\n\n# Runtime agent (execd) and sandbox images\n/components/execd/ @Pangjiping @hittyt @ninan-nn\n/components/ingress/ @Pangjiping @hittyt @Generalwin @Spground\n/components/egress/ @Pangjiping @hittyt @jwx0925\n/sandboxes/ @Pangjiping @ninan-nn @jwx0925 @hittyt @hellomypastor\n\n# Kubernetes controller\n/kubernetes/ @Spground @Generalwin @fengcone @kevinlynx @ninan-nn @hittyt @Pangjiping\n\n# SDKs\n/sdks/ @ninan-nn @jwx0925 @hittyt @hellomypastor\n\n# Specs and docs\n/specs/ @jwx0925 @hittyt @ninan-nn\n\n# OpenSandbox Enhancement Proposals\n/oseps/ @Spground @Generalwin @fengcone @kevinlynx @Pangjiping @ninan-nn @jwx0925 @hittyt\n" }, { "path": ".github/ISSUE_TEMPLATE/FEATURE_REQUEST.md", "content": "---\nname: Feature Request\nabout: Suggest an idea for OpenSandbox\ntitle: ''\nlabels: ''\nassignees: ''\n\n---\n\n## Why do you need it?\nIs your feature request related to a problem? Please describe in details\n\n\n## How could it be?\nA clear and concise description of what you want to happen. You can explain more about input of the feature, and output of it.\n\n\n## Other related information\nAdd any other context or screenshots about the feature request here.\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\ncontact_links:\n - name: Any Questions or Suggestions?\n url: https://github.com/alibaba/OpenSandbox/issues\n about: Please ask and answer questions here.\n" }, { "path": ".github/pull_request_template.md", "content": "# Summary\n- What is changing and why?\n\n# Testing\n- [ ] Not run (explain why)\n- [ ] Unit tests\n- [ ] Integration tests\n- [ ] e2e / manual verification\n\n# Breaking Changes\n- [ ] None\n- [ ] Yes (describe impact and migration path)\n\n# Checklist\n- [ ] Linked Issue or clearly described motivation\n- [ ] Added/updated docs (if needed)\n- [ ] Added/updated tests (if needed)\n- [ ] Security impact considered\n- [ ] Backward compatibility considered\n" }, { "path": ".github/workflows/deploy-docs-pages.yml", "content": "name: Deploy Docs Pages\n\non:\n push:\n branches:\n - main\n paths:\n - \"docs/**\"\n - \"specs/**\"\n - \"scripts/spec-doc/**\"\n - \"README.md\"\n - \"CONTRIBUTING.md\"\n - \"CODE_OF_CONDUCT.md\"\n - \"server/**/README*.md\"\n - \"server/**/DEVELOPMENT.md\"\n - \"components/**/README*.md\"\n - \"components/**/DEVELOPMENT.md\"\n - \"sdks/**/README*.md\"\n - \"sandboxes/**/README*.md\"\n - \"kubernetes/**/README*.md\"\n - \"examples/**/README*.md\"\n - \"specs/**/README*.md\"\n - \"oseps/**/*.md\"\n workflow_dispatch:\n\npermissions:\n contents: read\n pages: write\n id-token: write\n\nconcurrency:\n group: pages\n cancel-in-progress: false\n\njobs:\n build:\n runs-on: ubuntu-latest\n environment:\n name: github-pages\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n\n - name: Setup Pages\n id: pages\n uses: actions/configure-pages@v5\n\n - name: Setup Node 22\n uses: actions/setup-node@v6\n with:\n node-version: \"22\"\n\n - name: Setup pnpm\n uses: pnpm/action-setup@v4\n with:\n version: 9.15.0\n\n - name: Enable corepack\n run: corepack enable\n\n - name: Install docs dependencies\n working-directory: docs\n run: pnpm install --frozen-lockfile\n\n - name: Build docs\n working-directory: docs\n env:\n # Use root base when custom domain is configured via CNAME.\n DOCS_BASE: ${{ hashFiles('docs/public/CNAME') != '' && '/' || steps.pages.outputs.base_path }}\n run: pnpm docs:build\n\n - name: Upload artifact\n uses: actions/upload-pages-artifact@v4\n with:\n path: docs/.vitepress/dist\n\n deploy:\n runs-on: ubuntu-latest\n needs: build\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n steps:\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions/deploy-pages@v4\n" }, { "path": ".github/workflows/egress-test.yaml.yml", "content": "name: Egress Tests\n\non:\n pull_request:\n branches: [ main ]\n paths:\n - 'components/egress/**'\n - 'components/internal/**'\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.24.0'\n\n - name: Run Build\n working-directory: components/egress\n run: |\n go vet ./...\n go build .\n\n - name: Run tests\n working-directory: components/egress\n run: |\n go test ./...\n\n smoke:\n runs-on: self-hosted\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Run dns test\n working-directory: components/egress\n run: |\n chmod +x tests/smoke-dns.sh\n ./tests/smoke-dns.sh\n\n - name: Run nft test\n working-directory: components/egress\n run: |\n chmod +x tests/smoke-nft.sh\n ./tests/smoke-nft.sh\n\n - name: Run dynamic ip test\n working-directory: components/egress\n run: |\n chmod +x tests/smoke-dynamic-ip.sh\n ./tests/smoke-dynamic-ip.sh\n\n bench:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Run bench test\n working-directory: components/egress\n run: |\n chmod +x tests/bench-dns-nft.sh\n ./tests/bench-dns-nft.sh\n env:\n BENCH_SAMPLE_SIZE: \"20\"\n\n - name: Upload egress logs\n if: always()\n uses: actions/upload-artifact@v7\n with:\n name: egress-log-for-bench\n path: /tmp/egress-logs/\n retention-days: 5\n" }, { "path": ".github/workflows/execd-test.yml", "content": "name: Execd Tests\n\non:\n pull_request:\n branches: [ main ]\n paths:\n - 'components/execd/**'\n - 'components/internal/**'\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.24.0'\n\n - name: Run golint\n run: |\n cd components/execd\n make golint\n\n - name: Build (Multi platform compile)\n run: |\n cd components/execd\n #\n make multi-build\n\n - name: Run tests with coverage\n run: |\n cd components/execd\n go test -v -coverpkg=./... -coverprofile=coverage.out -covermode=atomic ./pkg/...\n\n - name: Calculate coverage and generate summary\n id: coverage\n run: |\n cd components/execd\n # Extract total coverage percentage\n TOTAL_COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}')\n echo \"total_coverage=$TOTAL_COVERAGE\" >> $GITHUB_OUTPUT\n \n # Generate GitHub Actions job summary\n echo \"## ๐Ÿ“Š execd Test Coverage Report\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"**Total Line Coverage:** $TOTAL_COVERAGE\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"Coverage report generated for commit \\`${{ github.sha }}\\`\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"---\" >> $GITHUB_STEP_SUMMARY\n echo \"*Coverage targets: Core packages >80%, API layer >70%*\" >> $GITHUB_STEP_SUMMARY\n\n smoke:\n strategy:\n fail-fast: false\n matrix:\n os: [ubuntu-latest, windows-latest]\n runs-on: ${{ matrix.os }}\n defaults:\n run:\n shell: bash\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.24.0'\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.10'\n\n - name: Install make (Windows)\n if: matrix.os == 'windows-latest'\n shell: powershell\n run: choco install make -y\n\n - name: Build\n run: |\n cd components/execd\n make build\n\n - name: Run smoke test\n run: |\n cd components/execd\n chmod +x tests/smoke.sh\n ./tests/smoke.sh\n\n sleep 5\n python3 tests/smoke_api.py\n - name: Show logs\n if: always()\n run: |\n set -x\n cat components/execd/startup.log || true\n cat components/execd/execd.log || true\n" }, { "path": ".github/workflows/ingress-test.yaml", "content": "name: Ingress Tests\n\non:\n pull_request:\n branches: [ main ]\n paths:\n - 'components/ingress/**'\n - 'components/internal/**'\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n permissions:\n contents: read\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.24.0'\n\n - name: Run golint\n working-directory: components/ingress\n run: |\n make golint\n\n - name: Run Build\n working-directory: components/ingress\n run: |\n make build\n\n - name: Run tests\n working-directory: components/ingress\n run: |\n make test\n" }, { "path": ".github/workflows/publish-components.yml", "content": "name: Publish Components Image\n\npermissions:\n # required for bump step to push branch and create PR\n contents: write\n pull-requests: write\n\non:\n workflow_dispatch:\n inputs:\n component:\n description: 'Component to build'\n required: true\n type: choice\n options:\n - execd\n - code-interpreter\n - ingress\n - egress\n - controller\n - task-executor\n default: 'execd'\n image_tag:\n description: 'Docker image tag'\n required: true\n default: 'latest'\n push:\n tags:\n - 'docker/execd/**'\n - 'docker/code-interpreter/**'\n - 'docker/ingress/**'\n - 'docker/egress/**'\n - 'k8s/controller/**'\n - 'k8s/task-executor/**'\n\njobs:\n publish:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up QEMU\n uses: docker/setup-qemu-action@v3\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v3\n\n - name: Login to DockerHub\n uses: docker/login-action@v3\n with:\n username: ${{ secrets.DOCKERHUB_USERNAME }}\n password: ${{ secrets.DOCKERHUB_PASSWORD }}\n\n - name: Login to ACR\n uses: docker/login-action@v3\n with:\n registry: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com\n username: ${{ secrets.ACR_USERNAME }}\n password: ${{ secrets.ACR_PASSWORD }}\n\n - name: Parse tag and set variables\n id: parse_tag\n run: |\n if [[ \"${{ github.ref }}\" == refs/tags/docker/* ]]; then\n TAG_PATH=\"${{ github.ref }}\"\n TAG_PATH=\"${TAG_PATH#refs/tags/}\"\n\n COMPONENT=$(echo \"$TAG_PATH\" | cut -d'/' -f2)\n IMAGE_TAG=$(echo \"$TAG_PATH\" | cut -d'/' -f3)\n\n echo \"component=$COMPONENT\" >> $GITHUB_OUTPUT\n echo \"image_tag=$IMAGE_TAG\" >> $GITHUB_OUTPUT\n elif [[ \"${{ github.ref }}\" == refs/tags/k8s/* ]]; then\n TAG_PATH=\"${{ github.ref }}\"\n TAG_PATH=\"${TAG_PATH#refs/tags/}\"\n\n COMPONENT=$(echo \"$TAG_PATH\" | cut -d'/' -f2)\n IMAGE_TAG=$(echo \"$TAG_PATH\" | cut -d'/' -f3)\n\n echo \"component=$COMPONENT\" >> $GITHUB_OUTPUT\n echo \"image_tag=$IMAGE_TAG\" >> $GITHUB_OUTPUT\n else\n echo \"component=${{ inputs.component }}\" >> $GITHUB_OUTPUT\n echo \"image_tag=${{ inputs.image_tag }}\" >> $GITHUB_OUTPUT\n fi\n\n - name: Free disk space\n run: |\n sudo rm -rf /usr/share/dotnet /opt/ghc /opt/hostedtoolcache\n sudo apt-get clean\n sudo rm -rf /var/lib/apt/lists/*\n df -h\n\n - name: Build and push to registries\n run: |\n COMPONENT=\"${{ steps.parse_tag.outputs.component }}\"\n IMAGE_TAG=\"${{ steps.parse_tag.outputs.image_tag }}\"\n\n if [ \"$COMPONENT\" == \"execd\" ]; then\n cd components/execd\n elif [ \"$COMPONENT\" == \"ingress\" ]; then\n cd components/ingress\n elif [ \"$COMPONENT\" == \"egress\" ]; then\n cd components/egress\n elif [ \"$COMPONENT\" == \"controller\" ]; then\n cd kubernetes\n elif [ \"$COMPONENT\" == \"task-executor\" ]; then\n cd kubernetes\n else\n cd sandboxes/$COMPONENT\n fi\n\n export TAG=$IMAGE_TAG\n export COMPONENT=$COMPONENT\n chmod +x build.sh\n ./build.sh\n\n - name: Bump component version in repo\n if: steps.parse_tag.outputs.image_tag != 'latest' && steps.parse_tag.outputs.image_tag != ''\n env:\n GH_TOKEN: ${{ github.token }}\n run: |\n COMPONENT=\"${{ steps.parse_tag.outputs.component }}\"\n IMAGE_TAG=\"${{ steps.parse_tag.outputs.image_tag }}\"\n # Ensure version has 'v' prefix for bump script\n if [[ \"$IMAGE_TAG\" =~ ^v ]]; then\n VERSION=\"$IMAGE_TAG\"\n else\n VERSION=\"v${IMAGE_TAG}\"\n fi\n\n ./scripts/bump-component-version.sh \"$COMPONENT\" \"$VERSION\"\n\n BRANCH=\"bump/${COMPONENT}-${VERSION}\"\n git config user.name \"github-actions[bot]\"\n git config user.email \"github-actions[bot]@users.noreply.github.com\"\n git checkout -b \"$BRANCH\"\n git add -A\n git diff --staged --quiet && echo \"No changes to commit\" && exit 0\n git commit -m \"chore: bump $COMPONENT to $VERSION\"\n git push origin \"$BRANCH\"\n\n gh pr create \\\n --title \"chore: bump $COMPONENT to $VERSION\" \\\n --body \"Auto-generated by Publish Components workflow after building \\`$COMPONENT:$VERSION\\`.\" \\\n --base \"$(gh api repos/${{ github.repository }} --jq .default_branch)\"\n" }, { "path": ".github/workflows/publish-csharp-sdks.yml", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nname: Publish C# SDKs\n\non:\n push:\n tags:\n - \"csharp/sandbox/v*\"\n - \"csharp/code-interpreter/v*\"\n\npermissions:\n contents: read\n\njobs:\n publish:\n name: Publish (${{ matrix.sdk.name }})\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n sdk:\n - name: sandbox\n tagPrefix: sandbox\n csprojPath: sdks/sandbox/csharp/src/OpenSandbox/OpenSandbox.csproj\n - name: code-interpreter\n tagPrefix: code-interpreter\n csprojPath: sdks/code-interpreter/csharp/src/OpenSandbox.CodeInterpreter/OpenSandbox.CodeInterpreter.csproj\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up .NET\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: \"10.0.x\"\n\n - name: Parse package version from tag\n if: startsWith(github.ref, format('refs/tags/csharp/{0}/v', matrix.sdk.tagPrefix))\n shell: bash\n run: |\n VERSION=\"${GITHUB_REF_NAME#csharp/${{ matrix.sdk.tagPrefix }}/v}\"\n echo \"PACKAGE_VERSION=$VERSION\" >> \"$GITHUB_ENV\"\n\n - name: Restore\n if: startsWith(github.ref, format('refs/tags/csharp/{0}/v', matrix.sdk.tagPrefix))\n run: |\n EXTRA_RESTORE_ARGS=\"\"\n if [ \"${{ matrix.sdk.name }}\" = \"code-interpreter\" ]; then\n EXTRA_RESTORE_ARGS=\"-p:UseLocalOpenSandboxProjectReference=false\"\n fi\n dotnet restore \"${{ matrix.sdk.csprojPath }}\" ${EXTRA_RESTORE_ARGS}\n\n - name: Pack\n if: startsWith(github.ref, format('refs/tags/csharp/{0}/v', matrix.sdk.tagPrefix))\n run: |\n EXTRA_PACK_ARGS=\"\"\n if [ \"${{ matrix.sdk.name }}\" = \"code-interpreter\" ]; then\n EXTRA_PACK_ARGS=\"-p:UseLocalOpenSandboxProjectReference=false\"\n fi\n dotnet pack \"${{ matrix.sdk.csprojPath }}\" \\\n --configuration Release \\\n --no-restore \\\n -p:PackageVersion=\"${PACKAGE_VERSION}\" \\\n -p:ContinuousIntegrationBuild=true \\\n ${EXTRA_PACK_ARGS} \\\n --output ./artifacts/${{ matrix.sdk.name }}\n\n - name: Publish to NuGet\n if: startsWith(github.ref, format('refs/tags/csharp/{0}/v', matrix.sdk.tagPrefix))\n env:\n NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}\n run: |\n dotnet nuget push \"./artifacts/${{ matrix.sdk.name }}/*.nupkg\" \\\n --api-key \"$NUGET_API_KEY\" \\\n --source \"https://api.nuget.org/v3/index.json\" \\\n --skip-duplicate\n" }, { "path": ".github/workflows/publish-helm-chart.yml", "content": "name: Publish Helm Chart\n\non:\n workflow_dispatch:\n inputs:\n component:\n description: 'Component to release'\n required: true\n type: choice\n options:\n - opensandbox-controller\n - opensandbox-server\n - opensandbox\n default: 'opensandbox-controller'\n app_version:\n description: 'App version (without v prefix, e.g., 0.1.0)'\n required: true\n default: '0.1.0'\n push:\n tags:\n - 'helm/**' # Format: helm//, e.g., helm/opensandbox-controller/0.1.0\n\njobs:\n publish:\n runs-on: ubuntu-latest\n permissions:\n contents: write\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n with:\n fetch-depth: 0\n\n - name: Configure Git\n run: |\n git config user.name \"$GITHUB_ACTOR\"\n git config user.email \"$GITHUB_ACTOR@users.noreply.github.com\"\n\n - name: Install Helm\n uses: azure/setup-helm@v4\n with:\n version: 'latest'\n\n - name: Parse tag and set variables\n id: parse_tag\n run: |\n if [[ \"${{ github.ref }}\" == refs/tags/helm/* ]]; then\n TAG_PATH=\"${{ github.ref }}\"\n TAG_PATH=\"${TAG_PATH#refs/tags/}\"\n \n COMPONENT=$(echo \"$TAG_PATH\" | cut -d'/' -f2)\n VERSION=$(echo \"$TAG_PATH\" | cut -d'/' -f3)\n \n # Remove 'v' prefix if present\n VERSION=${VERSION#v}\n \n echo \"component=$COMPONENT\" >> $GITHUB_OUTPUT\n echo \"app_version=$VERSION\" >> $GITHUB_OUTPUT\n else\n echo \"component=${{ inputs.component }}\" >> $GITHUB_OUTPUT\n echo \"app_version=${{ inputs.app_version }}\" >> $GITHUB_OUTPUT\n fi\n\n - name: Set chart path\n id: chart_path\n run: |\n COMPONENT=\"${{ steps.parse_tag.outputs.component }}\"\n \n if [ \"$COMPONENT\" == \"opensandbox-controller\" ]; then\n CHART_PATH=\"kubernetes/charts/opensandbox-controller\"\n elif [ \"$COMPONENT\" == \"opensandbox-server\" ]; then\n CHART_PATH=\"kubernetes/charts/opensandbox-server\"\n elif [ \"$COMPONENT\" == \"opensandbox\" ]; then\n CHART_PATH=\"kubernetes/charts/opensandbox\"\n else\n echo \"Error: Unknown component: $COMPONENT\"\n exit 1\n fi\n \n echo \"path=$CHART_PATH\" >> $GITHUB_OUTPUT\n\n - name: Get chart version from Chart.yaml\n id: chart_version\n run: |\n CHART_PATH=\"${{ steps.chart_path.outputs.path }}\"\n CHART_VERSION=$(grep '^version:' $CHART_PATH/Chart.yaml | awk '{print $2}')\n echo \"version=$CHART_VERSION\" >> $GITHUB_OUTPUT\n echo \"Chart version: $CHART_VERSION\"\n\n - name: Update Chart.yaml with app version\n run: |\n APP_VERSION=\"${{ steps.parse_tag.outputs.app_version }}\"\n CHART_PATH=\"${{ steps.chart_path.outputs.path }}\"\n \n # Only update appVersion, keep chart version as-is in Chart.yaml\n sed -i \"s/^appVersion:.*/appVersion: \\\"$APP_VERSION\\\"/\" $CHART_PATH/Chart.yaml\n \n echo \"Updated Chart.yaml:\"\n cat $CHART_PATH/Chart.yaml\n\n - name: Build dependencies (for opensandbox all-in-one chart)\n if: ${{ steps.parse_tag.outputs.component == 'opensandbox' }}\n run: |\n CHART_PATH=\"${{ steps.chart_path.outputs.path }}\"\n echo \"Building dependencies for all-in-one chart...\"\n helm dependency build $CHART_PATH\n\n - name: Lint Helm chart\n run: |\n CHART_PATH=\"${{ steps.chart_path.outputs.path }}\"\n helm lint $CHART_PATH\n\n - name: Package Helm chart\n run: |\n CHART_PATH=\"${{ steps.chart_path.outputs.path }}\"\n helm package $CHART_PATH\n\n - name: Create GitHub Release\n uses: softprops/action-gh-release@v1\n with:\n tag_name: helm/${{ steps.parse_tag.outputs.component }}/${{ steps.parse_tag.outputs.app_version }}\n name: Helm Chart ${{ steps.parse_tag.outputs.component }} ${{ steps.chart_version.outputs.version }} (App v${{ steps.parse_tag.outputs.app_version }})\n body: |\n ## ${{ steps.parse_tag.outputs.component }} Helm Chart\n \n **Chart Version:** ${{ steps.chart_version.outputs.version }}\n **App Version:** ${{ steps.parse_tag.outputs.app_version }}\n \n ### Installation\n \n ็›ดๆŽฅไปŽ GitHub Release ๅฎ‰่ฃ…:\n \n ```bash\n helm install ${{ steps.parse_tag.outputs.component }} \\\n https://github.com/${{ github.repository }}/releases/download/helm/${{ steps.parse_tag.outputs.component }}/${{ steps.parse_tag.outputs.app_version }}/${{ steps.parse_tag.outputs.component }}-${{ steps.chart_version.outputs.version }}.tgz \\\n --namespace opensandbox-system \\\n --create-namespace\n ```\n \n ๆˆ–่€…ๅ…ˆไธ‹่ฝฝๅŽๅฎ‰่ฃ…:\n \n ```bash\n # ไธ‹่ฝฝ\n wget https://github.com/${{ github.repository }}/releases/download/helm/${{ steps.parse_tag.outputs.component }}/${{ steps.parse_tag.outputs.app_version }}/${{ steps.parse_tag.outputs.component }}-${{ steps.chart_version.outputs.version }}.tgz\n \n # ๅฎ‰่ฃ…\n helm install ${{ steps.parse_tag.outputs.component }} ./${{ steps.parse_tag.outputs.component }}-${{ steps.chart_version.outputs.version }}.tgz \\\n --namespace opensandbox-system \\\n --create-namespace\n ```\n \n ${{ steps.parse_tag.outputs.component == 'opensandbox' && '**Note**: This is an all-in-one chart that bundles controller and server. The packaged chart already includes all dependencies, no need to run `helm dependency build` when installing from release.' || '' }}\n \n ### What's Changed\n \n - Chart version: ${{ steps.chart_version.outputs.version }}\n - App version: ${{ steps.parse_tag.outputs.app_version }}\n files: |\n ${{ steps.parse_tag.outputs.component }}-*.tgz\n draft: false\n prerelease: false\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/publish-java-sdks.yml", "content": "name: Publish Java SDKs\n\non:\n push:\n tags:\n - \"java/sandbox/v*\"\n - \"java/code-interpreter/v*\"\n\npermissions:\n contents: read\n\njobs:\n publish:\n name: Publish (${{ matrix.sdk.name }})\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n sdk:\n - name: sandbox\n tagPrefix: sandbox\n workingDirectory: sdks/sandbox/kotlin\n - name: code-interpreter\n tagPrefix: code-interpreter\n workingDirectory: sdks/code-interpreter/kotlin\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Java\n uses: actions/setup-java@v5\n with:\n distribution: temurin\n java-version: \"17\"\n\n - name: Set up Gradle\n uses: gradle/actions/setup-gradle@v5\n\n - name: Publish to Maven Central\n working-directory: ${{ matrix.sdk.workingDirectory }}\n if: startsWith(github.ref, format('refs/tags/java/{0}/v', matrix.sdk.tagPrefix))\n env:\n ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.ORG_GRADLE_PROJECT_MAVENCENTRALUSERNAME }}\n ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.ORG_GRADLE_PROJECT_MAVENCENTRALPASSWORD }}\n ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGINMEMORYKEY }}\n ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGINMEMORYKEYPASSWORD }}\n run: |\n ./gradlew publishAndReleaseToMavenCentral\n" }, { "path": ".github/workflows/publish-js-sdks.yml", "content": "name: Publish JavaScript SDKs\n\non:\n push:\n tags:\n - \"js/sandbox/v*\"\n - \"js/code-interpreter/v*\"\n\npermissions:\n contents: read\n\njobs:\n publish:\n name: Publish (${{ matrix.sdk.name }})\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n sdk:\n - name: sandbox\n tagPrefix: sandbox\n workingDirectory: sdks/sandbox/javascript\n packageName: \"@alibaba-group/opensandbox\"\n - name: code-interpreter\n tagPrefix: code-interpreter\n workingDirectory: sdks/code-interpreter/javascript\n packageName: \"@alibaba-group/opensandbox-code-interpreter\"\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Node\n uses: actions/setup-node@v6\n with:\n node-version: \"20\"\n registry-url: \"https://registry.npmjs.org\"\n\n - name: Set up pnpm\n uses: pnpm/action-setup@v4\n with:\n version: latest\n\n - name: Enable corepack\n run: corepack enable\n\n - name: Get pnpm store path\n id: pnpm-store\n run: echo \"STORE_PATH=$(corepack pnpm store path)\" >> \"$GITHUB_OUTPUT\"\n\n - name: Cache pnpm store\n uses: actions/cache@v5\n with:\n path: ${{ steps.pnpm-store.outputs.STORE_PATH }}\n key: ${{ runner.os }}-pnpm-${{ hashFiles('sdks/pnpm-lock.yaml') }}\n restore-keys: ${{ runner.os }}-pnpm-\n\n - name: Install workspace dependencies\n working-directory: sdks\n run: corepack pnpm install --frozen-lockfile\n\n - name: Build SDK\n working-directory: sdks\n run: corepack pnpm --filter ${{ matrix.sdk.packageName }}... --sort run build\n\n - name: Publish to npm\n if: startsWith(github.ref, format('refs/tags/js/{0}/v', matrix.sdk.tagPrefix))\n working-directory: ${{ matrix.sdk.workingDirectory }}\n env:\n NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n run: |\n corepack pnpm publish --access public --no-git-checks\n" }, { "path": ".github/workflows/publish-python-sdks.yml", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nname: Publish Python SDKs\n\npermissions:\n contents: read\n\non:\n push:\n tags:\n - \"python/sandbox/v*\"\n - \"python/code-interpreter/v*\"\n - \"python/mcp/sandbox/v*\"\n\njobs:\n publish-sandbox:\n if: startsWith(github.ref, 'refs/tags/python/sandbox/v')\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.10'\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n version: \"latest\"\n\n - name: Generate API\n working-directory: sdks/sandbox/python\n run: |\n uv run python scripts/generate_api.py\n\n - name: Build package\n working-directory: sdks/sandbox/python\n run: |\n uv build\n\n - name: Publish to PyPI\n working-directory: sdks/sandbox/python\n env:\n UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}\n run: |\n uv publish\n\n publish-code-interpreter:\n if: startsWith(github.ref, 'refs/tags/python/code-interpreter/v')\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.10'\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n version: \"latest\"\n\n - name: Build package\n working-directory: sdks/code-interpreter/python\n run: |\n uv build\n\n - name: Publish to PyPI\n working-directory: sdks/code-interpreter/python\n env:\n UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}\n run: |\n uv publish\n\n publish-mcp-sandbox:\n if: startsWith(github.ref, 'refs/tags/python/mcp/sandbox/v')\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: \"3.10\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n version: \"latest\"\n\n - name: Build package\n working-directory: sdks/mcp/sandbox/python\n run: |\n uv build\n\n - name: Publish to PyPI\n working-directory: sdks/mcp/sandbox/python\n env:\n UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}\n run: |\n uv publish\n" }, { "path": ".github/workflows/publish-server.yml", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nname: Publish Server\n\non:\n push:\n tags:\n - 'server/v*'\n\npermissions:\n contents: read\n\njobs:\n publish-pypi:\n if: startsWith(github.ref, 'refs/tags/server/v')\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.10'\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n version: \"latest\"\n\n - name: Build package\n working-directory: server\n run: |\n uv build\n\n - name: Publish to PyPI\n working-directory: server\n env:\n UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}\n run: |\n uv publish\n\n publish-image:\n if: startsWith(github.ref, 'refs/tags/server/v')\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n - name: Set up QEMU\n uses: docker/setup-qemu-action@v3\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v3\n\n - name: Login to DockerHub\n uses: docker/login-action@v3\n with:\n username: ${{ secrets.DOCKERHUB_USERNAME }}\n password: ${{ secrets.DOCKERHUB_PASSWORD }}\n\n - name: Login to ACR\n uses: docker/login-action@v3\n with:\n registry: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com\n username: ${{ secrets.ACR_USERNAME }}\n password: ${{ secrets.ACR_PASSWORD }}\n\n - name: Parse tag and set variables\n id: parse_tag\n run: |\n if [[ \"${{ github.ref }}\" == refs/tags/server/* ]]; then\n TAG_PATH=\"${{ github.ref }}\"\n TAG_PATH=\"${TAG_PATH#refs/tags/}\"\n\n IMAGE_TAG=\"${TAG_PATH#server/}\"\n\n if [ -z \"$IMAGE_TAG\" ]; then\n echo \"failed to parse image tag from $TAG_PATH\" >&2\n exit 1\n fi\n\n echo \"image_tag=$IMAGE_TAG\" >> $GITHUB_OUTPUT\n else\n echo \"cannot parse tag\"\n exit 1\n fi\n\n - name: Build and push to registries\n working-directory: server\n env:\n TAG: ${{ steps.parse_tag.outputs.image_tag }}\n run: |\n chmod +x build.sh\n ./build.sh\n" }, { "path": ".github/workflows/real-e2e.yml", "content": "name: Real E2E Tests\n\npermissions:\n contents: read\n\non:\n pull_request:\n branches: [ main ]\n paths:\n - 'server/src/**'\n - 'components/execd/**'\n - 'components/egress/**'\n - 'sdks/code-interpreter/**'\n - 'sdks/sandbox/**'\n - 'tests/**'\n push:\n branches: [ main ]\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\njobs:\n python-e2e:\n name: Python E2E (docker bridge)\n runs-on: self-hosted\n env:\n UV_BIN: /home/admin/.local/bin\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up uv PATH and verify\n run: |\n echo \"${UV_BIN}\" >> \"$GITHUB_PATH\"\n export PATH=\"${UV_BIN}:${PATH}\"\n uv --version\n uv run python --version\n\n - name: Clean up previous E2E resources\n run: |\n docker ps -aq --filter \"label=opensandbox\" | xargs -r docker rm -f || true\n # Remove root-owned files from previous sandbox runs by mounting parent dir\n docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true\n\n - name: Build local egress image\n run: docker build -t opensandbox/egress:local -f components/egress/Dockerfile .\n\n - name: Run tests\n run: |\n set -e\n\n # Create config file\n cat < ~/.sandbox.toml\n [server]\n host = \"127.0.0.1\"\n port = 8080\n log_level = \"INFO\"\n api_key = \"\"\n [runtime]\n type = \"docker\"\n execd_image = \"opensandbox/execd:local\"\n [egress]\n image = \"opensandbox/egress:local\"\n mode = \"dns\"\n [docker]\n network_mode = \"bridge\"\n [storage]\n allowed_host_paths = [\"/tmp/opensandbox-e2e\"]\n EOF\n\n ./scripts/python-e2e.sh\n\n - name: Eval server logs\n if: ${{ always() }}\n run: cat server/server.log\n\n - name: Upload execd logs\n if: always()\n uses: actions/upload-artifact@v7\n with:\n name: execd-log-for-python-e2e\n path: /tmp/opensandbox-e2e/logs/\n retention-days: 5\n\n - name: Clean up after E2E\n if: always()\n run: |\n docker ps -aq --filter \"label=opensandbox\" | xargs -r docker rm -f || true\n docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true\n pkill -f \"python -m src.main\" || true\n\n java-e2e:\n name: Java E2E (docker bridge)\n runs-on: self-hosted\n env:\n UV_BIN: /home/admin/.local/bin\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up uv PATH and verify\n run: |\n echo \"${UV_BIN}\" >> \"$GITHUB_PATH\"\n export PATH=\"${UV_BIN}:${PATH}\"\n uv --version\n uv run python --version\n\n - name: Set up JDK 8\n uses: actions/setup-java@v5\n with:\n distribution: temurin\n java-version: \"8\"\n\n - name: Set up JDK 17\n uses: actions/setup-java@v5\n with:\n distribution: temurin\n java-version: \"17\"\n\n - name: Clean up previous E2E resources\n run: |\n docker ps -aq --filter \"label=opensandbox\" | xargs -r docker rm -f || true\n docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true\n\n - name: Build local egress image\n run: docker build -t opensandbox/egress:local -f components/egress/Dockerfile .\n\n - name: Run tests\n env:\n GRADLE_USER_HOME: ${{ github.workspace }}/.gradle-user-home\n run: |\n set -e\n export GRADLE_OPTS=\"-Dorg.gradle.java.installations.auto-detect=true -Dorg.gradle.java.installations.auto-download=false -Dorg.gradle.java.installations.paths=${JAVA_HOME_8_X64},${JAVA_HOME_17_X64}\"\n\n # Create config file\n cat < ~/.sandbox.toml\n [server]\n host = \"127.0.0.1\"\n port = 8080\n log_level = \"INFO\"\n api_key = \"\"\n [runtime]\n type = \"docker\"\n execd_image = \"opensandbox/execd:local\"\n [egress]\n image = \"opensandbox/egress:local\"\n mode = \"dns+nft\"\n [docker]\n network_mode = \"bridge\"\n [storage]\n allowed_host_paths = [\"/tmp/opensandbox-e2e\"]\n EOF\n\n bash ./scripts/java-e2e.sh\n\n - name: Eval server logs\n if: ${{ always() }}\n run: cat server/server.log\n\n - name: Upload Test Report\n if: always()\n uses: actions/upload-artifact@v7\n with:\n name: java-test-report\n path: tests/java/build/reports/tests/test/\n retention-days: 5\n\n - name: Upload execd logs\n if: always()\n uses: actions/upload-artifact@v7\n with:\n name: execd-log-for-java-e2e\n path: /tmp/opensandbox-e2e/logs/\n retention-days: 5\n\n - name: Clean up after E2E\n if: always()\n run: |\n docker ps -aq --filter \"label=opensandbox\" | xargs -r docker rm -f || true\n docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true\n pkill -f \"python -m src.main\" || true\n\n javascript-e2e:\n name: JavaScript E2E (docker bridge)\n runs-on: self-hosted\n env:\n UV_BIN: /home/admin/.local/bin\n NODE_VERSION: \"20.19.0\"\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up uv PATH and verify\n run: |\n echo \"${UV_BIN}\" >> \"$GITHUB_PATH\"\n export PATH=\"${UV_BIN}:${PATH}\"\n uv --version\n uv run python --version\n\n - name: Set up Node.js\n run: |\n NODE_DIR=\"/home/admin/.local/node-v${NODE_VERSION}-linux-x64\"\n if [ -x \"${NODE_DIR}/bin/node\" ]; then\n echo \"Node.js ${NODE_VERSION} already cached\"\n else\n echo \"Downloading Node.js ${NODE_VERSION}...\"\n mkdir -p /home/admin/.local\n curl -fsSL \"https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz\" \\\n | tar -xJ -C /home/admin/.local/\n fi\n echo \"${NODE_DIR}/bin\" >> \"$GITHUB_PATH\"\n export PATH=\"${NODE_DIR}/bin:${PATH}\"\n node --version\n npm --version\n\n - name: Clean up previous E2E resources\n run: |\n docker ps -aq --filter \"label=opensandbox\" | xargs -r docker rm -f || true\n docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true\n\n - name: Build local egress image\n run: docker build -t opensandbox/egress:local -f components/egress/Dockerfile .\n\n - name: Run tests\n run: |\n set -e\n\n # Create config file (match other E2E jobs)\n cat < ~/.sandbox.toml\n [server]\n host = \"127.0.0.1\"\n port = 8080\n log_level = \"INFO\"\n api_key = \"\"\n [runtime]\n type = \"docker\"\n execd_image = \"opensandbox/execd:local\"\n [egress]\n image = \"opensandbox/egress:local\"\n [docker]\n network_mode = \"bridge\"\n [storage]\n allowed_host_paths = [\"/tmp/opensandbox-e2e\"]\n EOF\n\n bash ./scripts/javascript-e2e.sh\n\n - name: Eval server logs\n if: ${{ always() }}\n run: cat server/server.log\n\n - name: Upload Test Report\n if: always()\n uses: actions/upload-artifact@v7\n with:\n name: javascript-test-report\n path: tests/javascript/build/test-results/junit.xml\n retention-days: 5\n\n - name: Upload execd logs\n if: always()\n uses: actions/upload-artifact@v7\n with:\n name: execd-log-for-js-e2e\n path: /tmp/opensandbox-e2e/logs/\n retention-days: 5\n\n - name: Clean up after E2E\n if: always()\n run: |\n docker ps -aq --filter \"label=opensandbox\" | xargs -r docker rm -f || true\n docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true\n pkill -f \"python -m src.main\" || true\n\n csharp-e2e:\n name: C# E2E (docker bridge)\n runs-on: self-hosted\n env:\n UV_BIN: /home/admin/.local/bin\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up uv PATH and verify\n run: |\n echo \"${UV_BIN}\" >> \"$GITHUB_PATH\"\n export PATH=\"${UV_BIN}:${PATH}\"\n uv --version\n uv run python --version\n\n - name: Set up .NET SDK\n uses: actions/setup-dotnet@v5\n env:\n DOTNET_INSTALL_DIR: /home/admin/.local/dotnet\n with:\n dotnet-version: \"10.0.x\"\n\n - name: Clean up previous E2E resources\n run: |\n docker ps -aq --filter \"label=opensandbox\" | xargs -r docker rm -f || true\n docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true\n\n - name: Build local egress image\n run: docker build -t opensandbox/egress:local -f components/egress/Dockerfile .\n\n - name: Run tests\n run: |\n set -e\n\n cat < ~/.sandbox.toml\n [server]\n host = \"127.0.0.1\"\n port = 8080\n log_level = \"INFO\"\n api_key = \"\"\n [runtime]\n type = \"docker\"\n execd_image = \"opensandbox/execd:local\"\n [egress]\n image = \"opensandbox/egress:local\"\n [docker]\n network_mode = \"bridge\"\n [storage]\n allowed_host_paths = [\"/tmp/opensandbox-e2e\"]\n EOF\n\n bash ./scripts/csharp-e2e.sh\n\n - name: Eval server logs\n if: ${{ always() }}\n run: cat server/server.log\n\n - name: Upload Test Report\n if: always()\n uses: actions/upload-artifact@v7\n with:\n name: csharp-test-report\n path: tests/csharp/build/test-results/\n retention-days: 5\n\n - name: Upload execd logs\n if: always()\n uses: actions/upload-artifact@v7\n with:\n name: execd-log-for-csharp-e2e\n path: /tmp/opensandbox-e2e/logs/\n retention-days: 5\n\n - name: Clean up after E2E\n if: always()\n run: |\n docker ps -aq --filter \"label=opensandbox\" | xargs -r docker rm -f || true\n docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true\n pkill -f \"python -m src.main\" || true\n" }, { "path": ".github/workflows/sandbox-k8s-e2e.yml", "content": "name: Sandbox K8S E2E Tests\n\non:\n pull_request:\n branches: [ main ]\n paths:\n - 'kubernetes/**'\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\nenv:\n GO_VERSION: '1.24'\n\njobs:\n e2e-k8s:\n name: E2E Tests (K8s v${{ matrix.k8s-version }})\n strategy:\n fail-fast: false\n matrix:\n k8s-version: [\"1.21.1\", \"1.22.4\", \"1.24.4\", \"1.26.4\", \"1.28.6\", \"1.30.4\", \"1.32.2\", \"1.34.2\"]\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: ${{ env.GO_VERSION }}\n\n - name: Run tests\n run: |\n cd kubernetes\n make test-e2e KIND_K8S_VERSION=v${{ matrix.k8s-version }}" }, { "path": ".github/workflows/sandbox-k8s-test.yml", "content": "name: Sandbox K8S Tests\n\non:\n pull_request:\n branches: [ main ]\n paths:\n - 'kubernetes/**'\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.24.0'\n\n - name: Run golint\n run: |\n cd kubernetes\n make lint\n\n - name: Build binary\n run: |\n cd kubernetes\n make build\n make task-executor-build\n\n - name: Run tests\n run: |\n cd kubernetes\n make test\n" }, { "path": ".github/workflows/sdk-tests.yml", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nname: SDK Tests\n\non:\n pull_request:\n branches: [main]\n paths:\n - \"sdks/sandbox/**\"\n - \"sdks/code-interpreter/**\"\n - \"specs/**\"\n push:\n branches: [main]\n paths:\n - \"sdks/sandbox/**\"\n - \"sdks/code-interpreter/**\"\n - \"specs/**\"\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\njobs:\n python-sdk-quality:\n name: Python SDK Quality (${{ matrix.package_name }})\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n include:\n - package_name: sandbox\n package_dir: sdks/sandbox/python\n - package_name: code-interpreter\n package_dir: sdks/code-interpreter/python\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: \"3.11\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n version: \"latest\"\n\n - name: Install dependencies\n working-directory: ${{ matrix.package_dir }}\n run: |\n uv sync\n\n - name: Generate API\n if: matrix.package_name == 'sandbox'\n working-directory: sdks/sandbox/python\n run: |\n uv run python scripts/generate_api.py\n\n - name: Run ruff\n working-directory: ${{ matrix.package_dir }}\n run: |\n uv run ruff check\n\n - name: Run pyright\n working-directory: ${{ matrix.package_dir }}\n run: |\n uv run pyright\n\n python-sdk:\n name: Python SDK Tests\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: \"3.11\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n version: \"latest\"\n\n - name: Generate API\n working-directory: sdks/sandbox/python\n run: |\n uv sync\n uv run python scripts/generate_api.py\n\n - name: Run tests\n working-directory: sdks/sandbox/python\n run: |\n uv run pytest tests/ -v\n\n kotlin-sdk:\n name: Kotlin SDK Tests\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Java\n uses: actions/setup-java@v5\n with:\n distribution: temurin\n java-version: \"17\"\n\n - name: Set up Gradle\n uses: gradle/actions/setup-gradle@v5\n\n - name: Run tests\n working-directory: sdks/sandbox/kotlin\n run: |\n ./gradlew :sandbox:test\n\n csharp-sdk:\n name: C# SDK Tests\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up .NET 10\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: \"10.0.x\"\n\n - name: Run sandbox tests\n working-directory: sdks/sandbox/csharp\n run: |\n dotnet test tests/OpenSandbox.Tests/OpenSandbox.Tests.csproj --configuration Release\n\n - name: Run code interpreter tests\n working-directory: sdks/code-interpreter/csharp\n run: |\n dotnet test tests/OpenSandbox.CodeInterpreter.Tests/OpenSandbox.CodeInterpreter.Tests.csproj --configuration Release\n" }, { "path": ".github/workflows/server-test.yml", "content": "name: Server Tests\n\non:\n pull_request:\n branches: [ main ]\n paths:\n - 'server/src/**'\n - 'server/tests/**'\n\npermissions:\n contents: read\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n strategy:\n fail-fast: false\n matrix:\n os: [ubuntu-latest, windows-latest]\n runs-on: ${{ matrix.os }}\n defaults:\n run:\n shell: bash\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.10'\n\n - name: Install uv\n run: |\n pip install uv\n\n - name: Run tests\n run: |\n cd server\n uv sync --all-groups\n uv run ruff check\n uv run pytest\n\n docker-smoke:\n strategy:\n matrix:\n network: [host, bridge]\n runs-on: ubuntu-latest\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.10'\n\n - name: Install uv\n run: |\n pip install uv\n\n - name: Set up Docker\n run: |\n docker --version\n\n - name: Run smoke test\n run: |\n set -e\n cd server\n uv sync --all-groups\n\n # Create config file\n cat < ~/.sandbox.toml\n [server]\n host = \"127.0.0.1\"\n port = 32888\n log_level = \"INFO\"\n api_key = \"\"\n [runtime]\n type = \"docker\"\n execd_image = \"opensandbox/execd:latest\"\n [egress]\n image = \"opensandbox/egress:latest\"\n [docker]\n network_mode = \"${{ matrix.network }}\"\n [storage]\n allowed_host_paths = [\"/tmp/opensandbox-e2e\"]\n EOF\n\n # Start server in background\n uv run python -m src.main > app.log 2>&1 &\n\n # Wait for server to start\n sleep 10\n\n # Run smoke test\n chmod +x tests/smoke.sh\n ./tests/smoke.sh\n - name: Show logs\n if: always()\n run: |\n cat server/app.log\n" }, { "path": ".github/workflows/verify-license.yml", "content": "name: Verify License Headers\n\non:\n pull_request:\n branches: [ main ]\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}\n cancel-in-progress: true\n\njobs:\n verify-license:\n runs-on: self-hosted\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n - name: Run license verification\n run: |\n chmod +x scripts/verify-license.sh\n ./scripts/verify-license.sh\n" }, { "path": ".gitignore", "content": "# IDE and Editor files\n.vscode/\n.idea/\n*.swp\n*.swo\n*~\n.DS_Store\nThumbs.db\n\n# Go\n# Binaries for programs and plugins\n*.exe\n*.exe~\n*.dll\n*.so\n*.dylib\n\n# Test binary, built with `go test -c`\n*.test\n\n# Output of the go coverage tool\n*.out\n\n# Dependency directories\nvendor/\n\n# Go workspace file\ngo.work\n\n# Java/Kotlin\n# Compiled class file\n*.class\n\n# Log file\n*.log\n\n# BlueJ files\n*.ctxt\n\n# Mobile Tools for Java (J2ME)\n.mtj.tmp/\n\n# Package Files\n*.jar\n*.war\n*.nar\n*.ear\n*.zip\n*.tar.gz\n*.rar\n\n# virtual machine crash logs\nhs_err_pid*\nreplay_pid*\n\n# Gradle\n.gradle/\nbuild/\n!**/gradle/wrapper/gradle-wrapper.jar\n!**/src/main/**/build/\n!**/src/test/**/build/\n\n# Maven\ntarget/\npom.xml.tag\npom.xml.releaseBackup\npom.xml.versionsBackup\npom.xml.next\nrelease.properties\ndependency-reduced-pom.xml\nbuildNumber.properties\n.mvn/timing.properties\n.mvn/wrapper/maven-wrapper.jar\n\n# Node.js\n# Logs\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\nlerna-debug.log*\n.pnpm-debug.log*\n\n# Dependency directories\nnode_modules/\njspm_packages/\n\n# TypeScript cache\n*.tsbuildinfo\n\n# Optional npm cache directory\n.npm\n\n# Optional eslint cache\n.eslintcache\n\n# Optional stylelint cache\n.stylelintcache\n\n# Microbundle cache\n.rpt2_cache/\n.rts2_cache_cjs/\n.rts2_cache_es/\n.rts2_cache_umd/\n\n# Optional REPL history\n.node_repl_history\n\n# Output of 'npm pack'\n*.tgz\n\n# Yarn Integrity file\n.yarn-integrity\n\n# Yarn v2\n.yarn/cache\n.yarn/unplugged\n.yarn/build-state.yml\n.yarn/install-state.gz\n.pnp.*\n\n# parcel-bundler cache (https://parceljs.org/)\n.cache\n.parcel-cache\n\n# Next.js build output\n.next\nout\n\n# Nuxt.js build / generate output\n.nuxt\ndist\n\n# Gatsby files\n.cache/\npublic\n!docs/public/\n!docs/public/CNAME\n\n# Serverless directories\n.serverless/\n\n# FuseBox cache\n.fusebox/\n\n# DynamoDB Local files\n.dynamodb/\n\n# TernJS port file\n.tern-port\n\n# Stores VSCode versions used for testing VSCode extensions\n.vscode-test\n\n# yarn v2\n.yarn/cache\n.yarn/unplugged\n.yarn/build-state.yml\n.yarn/install-state.gz\n.pnp.*\n\n# Python\n__pycache__/\n*.py[cod]\n*$py.class\n*.so\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# Virtual environments\nvenv/\nenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# Docker\n*.pid\n*.seed\n*.pid.lock\n\n# OS generated files\n.DS_Store\n.DS_Store?\n._*\n.Spotlight-V100\n.Trashes\nehthumbs.db\nThumbs.db\n\n# Temporary files\n*.tmp\n*.temp\n*~\n\n# Environment variables\n.env\n.env.local\n.env.development.local\n.env.test.local\n.env.production.local\n\n# API keys and secrets\nsecrets/\n*.pem\n*.key\n*.crt\n*.p12\n*.pfx\n\n# Generated API documentation\ndocs/generated/\ndocs/.vitepress/generated/\ndocs/.vitepress/dist/\ndocs/.vitepress/cache/\napidocs/\n\n# Test results\ntest-results/\ncoverage/\n*.coverage\n.nyc_output\n\n# Backup files\n*.bak\n*.backup\n*.old\n\n# Flattened POM files (Maven)\n.flattened-pom.xml\n\n# Kotlin\n*.kotlin_module\n\n# JetBrains specific\n.idea/\n*.iml\n*.ipr\n*.iws\nout/\n\n# Eclipse specific\n.project\n.classpath\n.settings/\nbin/\n\n# NetBeans specific\nnbproject/\nnbbuild/\nnbdist/\n.nb-gradle/\n\n# Generated files\ngenerated/\n**/generated/**\n\n# gVisor runtime binaries (downloaded dynamically)\nkubernetes/test/kind/gvisor/runsc\nkubernetes/test/kind/gvisor/containerd-shim-runsc-v1\nbin/\nobj/\n" }, { "path": ".pre-commit-config.yaml", "content": "# Minimal cross-language pre-commit hooks\n# Install: pip install pre-commit && pre-commit install\n# Run once on all files: pre-commit run --all-files\n\nrepos:\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.6.0\n hooks:\n - id: trailing-whitespace\n - id: end-of-file-fixer\n - id: mixed-line-ending\n - id: check-merge-conflict\n - id: check-yaml\n - id: detect-private-key\n\n # Language-specific formatters/linters can be added later, for example:\n # - repo: local\n # hooks:\n # - id: gofmt\n # name: gofmt\n # entry: gofmt\n # language: system\n # types: [go]\n # - id: ruff\n # name: ruff\n # entry: ruff check\n # language: system\n # types: [python]\n" }, { "path": "AGENTS.md", "content": "# Repository Guidelines\n\n## Project Structure & Module Organization\n- `server/`: Python FastAPI service, configs, and tests.\n- `components/execd/`: Go execution daemon and related tests.\n- `sdks/`: Multi-language SDKs (`sdks/sandbox/*`, `sdks/code-interpreter/*`).\n- `sandboxes/`: Runtime sandbox implementations (e.g., `sandboxes/code-interpreter/`).\n- `specs/`: OpenAPI specs (`specs/execd-api.yaml`, `specs/sandbox-lifecycle.yml`).\n- `examples/`: End-to-end usage examples and integrations.\n- `tests/`: Cross-component/E2E tests (`tests/python/`, `tests/java/`).\n- `docs/`, `oseps/`, `scripts/`: Docs, proposals, and automation scripts.\n\n## Build, Test, and Development Commands\n- Server (Python):\n - `cd server && uv sync` installs deps.\n - `cp server/example.config.toml ~/.sandbox.toml` sets local config.\n - `cd server && uv run python -m src.main` runs the API server.\n- execd (Go):\n - `cd components/execd && go build -o bin/execd .` builds the daemon.\n - `cd components/execd && make fmt` formats Go sources.\n- SDKs:\n - Python: `cd sdks/sandbox/python && uv sync && uv run pytest`.\n - Kotlin: `cd sdks/sandbox/kotlin && ./gradlew build`.\n- Specs: `node scripts/spec-doc/generate-spec.js` regenerates spec docs.\n\n## Coding Style & Naming Conventions\n- Python: PEP 8, `ruff` for lint/format, type hints on public APIs.\n- Go: `gofmt`, explicit error handling, standard import grouping.\n- Kotlin: Kotlin Coding Conventions, `ktlint` where configured.\n- Naming: classes `PascalCase`, functions `snake_case` (Python) / `camelCase` (Go/Kotlin), constants `UPPER_SNAKE_CASE`.\n\n## SDK API Implementation Conventions\n- Keep a clear split between generated API transport code and handwritten SDK business/adaptor code.\n- In adapter/infrastructure layers, default to integrating through generated API clients instead of handcrafted request wiring.\n- Prefer generated OpenAPI clients for standard request/response endpoints; use handwritten transport only for streaming or protocol-specific paths (for example SSE).\n- Do not manually edit generated client files. When specs change, regenerate first, then adapt handwritten layers.\n- For handwritten streaming paths, keep wire contracts aligned with OpenAPI field names/models and cover behavior with focused tests (especially parsing and error mapping).\n\n## Testing Guidelines\n- Python tests use `pytest` (async tests common).\n- Go tests use `go test` under `components/execd/pkg/...`.\n- Kotlin tests use Gradle (`./gradlew test`).\n- Coverage targets (from CONTRIBUTING): core packages >80%, API layer >70%.\n\n## Commit & Pull Request Guidelines\n- Commit messages follow Conventional Commits, e.g. `feat(server): add runtime`.\n- Use feature branches (e.g., `feature/...`, `fix/...`) and keep PRs focused.\n- PRs should include summary, testing status, and linked issues; follow the template in `CONTRIBUTING.md`.\n- For major API or architectural changes, submit an OSEP (`oseps/`).\n\n## Security & Configuration Tips\n- Local server config lives in `~/.sandbox.toml` (copied from `server/example.config.toml`).\n- Docker is required for local sandbox execution; keep images and keys out of commits.\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "# Code of Conduct\n\nWe are committed to a welcoming, safe, and respectful community.\n\n## Expected Behavior\n- Be respectful and inclusive.\n- Assume good intent; seek to understand.\n- Provide constructive feedback; critique code, not people.\n- Follow project guidelines and security practices.\n\n## Unacceptable Behavior\n- Harassment, personal attacks, or discriminatory language.\n- Publishing private information without consent.\n- Disruptive or aggressive behavior in any project space.\n\n## Scope\nThis Code applies to all project spaces, including issues, pull requests, discussions, chat, and events.\n\n## Reporting\nReport incidents to: **conduct@opensandbox.io**. Include as much detail as possible (what happened, when/where, links, screenshots if applicable).\n\n## Enforcement\nMaintainers will investigate in good faith and may take appropriate action, including warnings, temporary bans, or removal from the community.\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing to OpenSandbox\n\nThank you for your interest in contributing to OpenSandbox! This guide will help you get started with contributing to the project, whether you're fixing bugs, adding features, improving documentation, or helping in other ways.\n\n## Table of Contents\n\n- [Code of Conduct](#code-of-conduct)\n- [Getting Started](#getting-started)\n- [Development Environment Setup](#development-environment-setup)\n- [Project Structure](#project-structure)\n- [Development Workflow](#development-workflow)\n- [Coding Standards](#coding-standards)\n- [Testing Guidelines](#testing-guidelines)\n- [Submitting Contributions](#submitting-contributions)\n- [Communication Channels](#communication-channels)\n\n## Code of Conduct\n\nOpenSandbox adheres to a [Code of Conduct](CODE_OF_CONDUCT.md) that we expect all contributors to follow. Please read it before contributing to ensure a welcoming and inclusive environment for everyone.\n\n## Getting Started\n\n### Ways to Contribute\n\nThere are many ways to contribute to OpenSandbox:\n\n- **Report Bugs**: Submit detailed bug reports through [GitHub Issues](https://github.com/alibaba/OpenSandbox/issues)\n- **Suggest Features**: Propose new features or improvements\n- **Write Code**: Fix bugs, implement features, or improve performance\n- **Improve Documentation**: Enhance README files, write tutorials, or fix typos\n- **Write Tests**: Add test coverage or improve existing tests\n- **Review Pull Requests**: Help review and test others' contributions\n- **Answer Questions**: Help other users in GitHub Discussions or Issues\n\n### Before You Start\n\n1. **Search Existing Issues**: Check if your bug report or feature request already exists\n2. **Check Roadmap**: Review the project roadmap to see if your idea aligns with project goals\n3. **Discuss Major Changes**: For significant changes, open an issue first or submit an [OSEP](oseps/README.md) to discuss your approach\n4. **Review Architecture**: Read [docs/architecture.md](docs/architecture.md) to understand the system design\n\n## Development Environment Setup\n\n### Prerequisites\n\nDifferent components have different requirements:\n\n#### For Server (Python)\n\n- **Python 3.10+**\n- **uv** - Python package manager ([installation guide](https://github.com/astral-sh/uv))\n- **Docker** - For running sandboxes locally\n\n#### For execd (Go)\n\n- **Go 1.24+**\n- **Make** - Build automation (optional)\n- **Docker** - For building container images\n\n#### For SDKs\n\n- **Python SDK**: Python 3.10+, uv\n- **Java/Kotlin SDK**: JDK 17+, Gradle\n\n### Quick Setup\n\n#### Server Development\n\n```bash\n# Navigate to server directory\ncd server\n\n# Install dependencies\nuv sync\n\n# Copy example configuration\ncp example.config.toml ~/.sandbox.toml\n\n# Edit configuration for development\n# Set log_level = \"DEBUG\" and api_key\nnano ~/.sandbox.toml\n\n# Run server\nuv run python -m src.main\n```\n\nSee [server/DEVELOPMENT.md](server/DEVELOPMENT.md) for detailed server development guide.\n\n#### execd Development\n\n```bash\n# Navigate to execd directory\ncd components/execd\n\n# Download dependencies\ngo mod download\n\n# Build execd\ngo build -o bin/execd .\n\n# Run execd (requires Jupyter Server)\n./bin/execd --jupyter-host=http://localhost:8888 --port=44772\n```\n\nSee [components/execd/DEVELOPMENT.md](components/execd/DEVELOPMENT.md) for detailed execd development guide.\n\n#### SDK Development\n\n**Python SDK:**\n\n```bash\ncd sdks/sandbox/python\nuv sync\nuv run pytest\n```\n\n**Java/Kotlin SDK:**\n\n```bash\ncd sdks/sandbox/kotlin\n./gradlew build\n./gradlew test\n```\n\n## Project Structure\n\n```\nOpenSandbox/\nโ”œโ”€โ”€ sdks/ # Multi-language SDKs\nโ”‚ โ”œโ”€โ”€ code-interpreter/ # Code Interpreter SDK (Python, Kotlin)\nโ”‚ โ””โ”€โ”€ sandbox/ # Sandbox base SDK (Python, Kotlin)\nโ”œโ”€โ”€ specs/ # OpenAPI specifications\nโ”‚ โ”œโ”€โ”€ execd-api.yaml # Execution API spec\nโ”‚ โ””โ”€โ”€ sandbox-lifecycle.yml # Lifecycle API spec\nโ”œโ”€โ”€ server/ # Sandbox server (Python/FastAPI)\nโ”œโ”€โ”€ components/\nโ”‚ โ””โ”€โ”€ execd/ # Execution daemon (Go/Beego)\nโ”œโ”€โ”€ sandboxes/ # Sandbox implementations\nโ”‚ โ””โ”€โ”€ code-interpreter/ # Code Interpreter sandbox\nโ”œโ”€โ”€ examples/ # Example integrations\nโ”œโ”€โ”€ docs/ # Documentation\nโ”œโ”€โ”€ tests/ # Cross-component tests\nโ”‚ โ””โ”€โ”€ e2e/ # End-to-end tests\nโ””โ”€โ”€ scripts/ # Build and utility scripts\n```\n\n## Development Workflow\n\n### Enhancement Proposals (OSEP)\n\nFor major features, architectural changes, or modifications to the core API/security model, we follow the **OSEP (OpenSandbox Enhancement Proposals)** process.\n\nPlease read the [OSEP README](oseps/README.md) to understand when an OSEP is required and how to submit one. Small bug fixes and minor improvements do not require an OSEP.\n\n### Branching Strategy\n\n- **main**: Stable production branch\n- **feature/[name]**: New features\n- **fix/[name]**: Bug fixes\n- **docs/[name]**: Documentation updates\n- **refactor/[name]**: Code refactoring\n- **test/[name]**: Test additions or improvements\n\n### Creating a Feature Branch\n\n```bash\n# Update main branch\ngit checkout main\ngit pull origin main\n\n# Create feature branch\ngit checkout -b feature/my-awesome-feature\n\n# Make your changes\n# ...\n\n# Commit your changes\ngit add .\ngit commit -m \"feat: add my awesome feature\"\n\n# Push to your fork\ngit push origin feature/my-awesome-feature\n```\n\n### Commit Message Format\n\nWe follow [Conventional Commits](https://www.conventionalcommits.org/) specification:\n\n```\n(): \n\n[optional body]\n\n[optional footer]\n```\n\n**Types:**\n\n- `feat`: New feature\n- `fix`: Bug fix\n- `docs`: Documentation changes\n- `style`: Code style changes (formatting, no logic change)\n- `refactor`: Code refactoring\n- `test`: Adding or updating tests\n- `chore`: Build process, dependencies, or tooling changes\n- `perf`: Performance improvements\n- `ci`: CI/CD changes\n\n**Examples:**\n\n```\nfeat(server): add Kubernetes runtime support\nfix(execd): resolve memory leak in session cleanup\ndocs(sdk): add Python SDK usage examples\ntest(server): add integration tests for Docker runtime\nrefactor(sdk): simplify filesystem API\n```\n\n### Making Changes\n\n1. **Write Clean Code**: Follow project coding standards (see below)\n2. **Add Tests**: Ensure your changes are covered by tests\n3. **Update Documentation**: Update relevant documentation files\n4. **Test Locally**: Run all tests and ensure they pass\n5. **Check Linting**: Run linters and fix any issues\n\n## Coding Standards\n\n### Python (Server, Python SDKs)\n\n- **Style Guide**: Follow [PEP 8](https://pep8.org/)\n- **Formatter**: Use `ruff` for formatting and linting\n- **Type Hints**: Always use type hints for function signatures\n- **Docstrings**: Use Google-style docstrings for public APIs\n\n```python\ndef create_sandbox(\n image: ImageSpec,\n timeout: timedelta,\n entrypoint: Optional[List[str]] = None\n) -> Sandbox:\n \"\"\"Create a new sandbox instance.\n\n Args:\n image: Container image specification\n timeout: Sandbox timeout duration\n entrypoint: Optional custom entrypoint command\n\n Returns:\n Created sandbox instance\n\n Raises:\n ValueError: If image or timeout is invalid\n \"\"\"\n # Implementation\n```\n\n**Running Linter:**\n\n```bash\ncd server\nuv run ruff check src tests\nuv run ruff format src tests\n```\n\n### Go (execd)\n\n- **Style Guide**: Follow [Effective Go](https://golang.org/doc/effective_go)\n- **Formatter**: Use `gofmt` for formatting\n- **Imports**: Organize in three groups (stdlib, third-party, internal)\n- **Error Handling**: Always handle errors explicitly\n\n```go\n// Good\nresult, err := someOperation()\nif err != nil {\n logs.Error(\"operation failed: %v\", err)\n return fmt.Errorf(\"failed to do something: %w\", err)\n}\n\n// Bad - silent failure\nresult, _ := someOperation()\n```\n\n**Running Formatter:**\n\n```bash\ncd components/execd\ngofmt -w .\n# Or\nmake fmt\n```\n\n### Java/Kotlin (Java/Kotlin SDKs)\n\n- **Style Guide**: Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/coding-conventions.html)\n- **Formatter**: Use `ktlint`\n- **Null Safety**: Use Kotlin's null safety features\n\n```kotlin\nsuspend fun createSandbox(\n image: ImageSpec,\n timeout: Duration,\n entrypoint: List? = null\n): Sandbox {\n // Implementation\n}\n```\n\n### General Guidelines\n\n- **Naming Conventions**:\n - Functions/Methods: `snake_case` (Python), `camelCase` (Go, Kotlin)\n - Classes: `PascalCase` (all languages)\n - Constants: `UPPER_SNAKE_CASE` (all languages)\n - Private members: `_leading_underscore` (Python), `unexported` (Go)\n\n- **Comments**: Write clear, concise comments explaining \"why\", not \"what\"\n- **Error Messages**: Provide actionable error messages with context\n- **Logging**: Use appropriate log levels (DEBUG, INFO, WARNING, ERROR)\n\n## Testing Guidelines\n\n### Test Coverage Requirements\n\n- **Core Packages**: Aim for >80% coverage\n- **API Layer**: Aim for >70% coverage\n- **Utilities**: Aim for >90% coverage\n\n### Writing Tests\n\n#### Python Tests (pytest)\n\n```python\nimport pytest\nfrom opensandbox import Sandbox\n\n@pytest.mark.asyncio\nasync def test_create_sandbox():\n \"\"\"Test sandbox creation with valid parameters.\"\"\"\n sandbox = await Sandbox.create(\n image=\"python:3.11\",\n timeout=timedelta(minutes=5)\n )\n assert sandbox.id is not None\n assert sandbox.status == SandboxStatus.PENDING\n await sandbox.kill()\n\n@pytest.mark.asyncio\nasync def test_invalid_timeout():\n \"\"\"Test sandbox creation fails with invalid timeout.\"\"\"\n with pytest.raises(ValueError):\n await Sandbox.create(\n image=\"python:3.11\",\n timeout=timedelta(seconds=-1)\n )\n```\n\n**Running Tests:**\n\n```bash\ncd server\nuv run pytest\nuv run pytest --cov=src --cov-report=html\n```\n\n#### Go Tests\n\n```go\nfunc TestController_Execute_Python(t *testing.T) {\n ctrl := NewController(\"http://localhost:8888\", \"test-token\")\n\n req := &ExecuteCodeRequest{\n Language: Python,\n Code: \"print('hello')\",\n }\n\n err := ctrl.Execute(req)\n assert.NoError(t, err)\n}\n```\n\n**Running Tests:**\n\n```bash\ncd components/execd\ngo test ./pkg/...\ngo test -v -cover ./pkg/...\n```\n\n#### Integration Tests\n\nIntegration tests require Docker:\n\n```bash\n# Server integration tests\ncd server\nuv run pytest tests/integration/\n\n# E2E tests\ncd tests/e2e/python\nuv run pytest\n```\n\n### Test Best Practices\n\n- **Test Names**: Use descriptive names that explain what is being tested\n- **Arrange-Act-Assert**: Structure tests clearly\n- **Isolation**: Each test should be independent\n- **Mocking**: Mock external dependencies appropriately\n- **Cleanup**: Always clean up resources (use fixtures, context managers)\n\n## Submitting Contributions\n\n### Pull Request Process\n\n1. **Create Feature Branch**: Branch from `main`\n2. **Make Changes**: Implement your feature or fix\n3. **Write Tests**: Add comprehensive test coverage\n4. **Update Documentation**: Update relevant docs\n5. **Test Locally**: Ensure all tests pass\n6. **Run Linters**: Fix any style issues\n7. **Commit Changes**: Use conventional commit messages\n8. **Push to Fork**: Push your branch to your fork\n9. **Create Pull Request**: Submit PR with detailed description\n\n### Pull Request Template\n\nWhen creating a PR, fill out the template:\n\n```markdown\n# Summary\n\n- What is changing and why?\n\n# Testing\n\n- [ ] Not run (explain why)\n- [ ] Unit tests\n- [ ] Integration tests\n- [ ] e2e / manual verification\n\n# Breaking Changes\n\n- [ ] None\n- [ ] Yes (describe impact and migration path)\n\n# Checklist\n\n- [ ] Linked Issue or clearly described motivation\n- [ ] Added/updated docs (if needed)\n- [ ] Added/updated tests (if needed)\n- [ ] Security impact considered\n- [ ] Backward compatibility considered\n```\n\n### Pull Request Guidelines\n\n**Do:**\n\n- Keep PRs focused and reasonably sized (< 500 lines if possible)\n- Write clear PR descriptions with motivation and context\n- Link related issues\n- Respond to review comments promptly\n- Update your PR based on feedback\n- Ensure CI passes before requesting review\n\n**Don't:**\n\n- Mix multiple unrelated changes in one PR\n- Submit PRs with failing tests\n- Ignore code review feedback\n- Force push after reviews have started (unless necessary)\n- Include commented-out code or debug statements\n\n### Code Review Process\n\n1. **Automated Checks**: CI runs tests, linters, and security scans\n2. **Maintainer Review**: A maintainer reviews your code\n3. **Feedback Loop**: Address review comments\n4. **Approval**: Once approved, a maintainer will merge your PR\n5. **Cleanup**: Delete your feature branch after merge\n\n## Communication Channels\n\n### GitHub Issues\n\nUse GitHub Issues for:\n\n- Bug reports\n- Feature requests\n- Documentation improvements\n- Questions about implementation\n\n**Bug Report Template:**\n\n```markdown\n**Description**\nA clear description of the bug.\n\n**To Reproduce**\nSteps to reproduce the behavior:\n\n1. Create sandbox with...\n2. Execute command...\n3. See error\n\n**Expected Behavior**\nWhat you expected to happen.\n\n**Environment**\n\n- OpenSandbox version:\n- Runtime (Docker/K8s):\n- OS:\n- Python/Go version:\n\n**Additional Context**\nLogs, screenshots, or other relevant information.\n```\n\n### GitHub Discussions\n\nUse GitHub Discussions for:\n\n- General questions\n- Design discussions\n- Brainstorming ideas\n- Community help\n\n### Getting Help\n\n- **Issues**: Technical problems or bugs\n- **Discussions**: Questions and community support\n- **Email**: For security issues, email conduct@opensandbox.io\n\n## Additional Resources\n\n### Documentation\n\n- [Architecture Overview](docs/architecture.md)\n- [Server Development Guide](server/DEVELOPMENT.md)\n- [execd Development Guide](components/execd/DEVELOPMENT.md)\n- [OpenAPI Specifications](specs/README.md)\n- [Python SDK Documentation](sdks/sandbox/python/README.md)\n- [Java/Kotlin SDK Documentation](sdks/sandbox/kotlin/README.md)\n\n### Examples\n\nBrowse [examples/](examples/) for real-world usage patterns:\n\n- Code Interpreter integration\n- AI Coding Agent integrations (Claude Code, Gemini CLI, etc.)\n- Browser automation (Chrome, Playwright)\n- Remote development (VS Code, Desktop)\n\n### External Resources\n\n- [FastAPI Documentation](https://fastapi.tiangolo.com/)\n- [Beego Documentation](https://beego.wiki/)\n- [Jupyter Protocol](https://jupyter-client.readthedocs.io/en/stable/messaging.html)\n- [OpenAPI Specification](https://swagger.io/specification/)\n- [Docker API](https://docs.docker.com/engine/api/)\n\n## Acknowledgments\n\nThank you for contributing to OpenSandbox! Your contributions help make this project better for everyone in the AI and developer tools community.\n\nIf you have suggestions for improving this contributing guide, please open an issue or submit a pull request.\n\n## License\n\nBy contributing to OpenSandbox, you agree that your contributions will be licensed under the [Apache 2.0 License](LICENSE).\n" }, { "path": "LICENSE", "content": "Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n" }, { "path": "README.md", "content": "
\n \"OpenSandbox\n\n

OpenSandbox

\n\n

\n \n \"alibaba%2FOpenSandbox\n \n

\n\n

\n \n \"GitHub\n \n \n \"Ask\n \n \n \"license\"\n \n \n \"PyPI\n \n \n \"npm\n \n \n \"CNCF\n \n \n \"DingTalk\"\n \n \n \"E2E\n \n

\n\n
\n
\n\n[Documentation](https://open-sandbox.ai/) | [ไธญๆ–‡ๆ–‡ๆกฃ](https://open-sandbox.ai/zh/)\n\nOpenSandbox is a **general-purpose sandbox platform** for AI applications, offering multi-language SDKs, unified sandbox APIs, and Docker/Kubernetes runtimes for scenarios like Coding Agents, GUI Agents, Agent Evaluation, AI Code Execution, and RL Training.\n\nOpenSandbox is now listed in the [CNCF Landscape](https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox).\n\n## Features\n\n- **Multi-language SDKs**: Provides sandbox SDKs in Python, Java/Kotlin, JavaScript/TypeScript, C#/.NET, Go (Roadmap), and more.\n- **Sandbox Protocol**: Defines sandbox lifecycle management APIs and sandbox execution APIs so you can extend custom sandbox runtimes.\n- **Sandbox Runtime**: Built-in lifecycle management supporting Docker and [high-performance Kubernetes runtime](./kubernetes), enabling both local runs and large-scale distributed scheduling.\n- **Sandbox Environments**: Built-in Command, Filesystem, and Code Interpreter implementations. Examples cover Coding Agents (e.g., Claude Code), browser automation (Chrome, Playwright), and desktop environments (VNC, VS Code).\n- **Network Policy**: Unified [Ingress Gateway](components/ingress) with multiple routing strategies plus per-sandbox [egress controls](components/egress).\n- **Strong Isolation**: Supports secure container runtimes like gVisor, Kata Containers, and Firecracker microVM for enhanced isolation between sandbox workloads and the host. See [Secure Container Runtime Guide](docs/secure-container.md) for details.\n\n## Examples\n\n### Basic Sandbox Operations\n\nRequirements:\n\n- Docker (required for local execution)\n- Python 3.10+ (recommended for examples and local runtime)\n\n#### 1. Install and Configure the Sandbox Server\n\n```bash\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker\n```\n\n> If you prefer working from source, you can still clone the repo for development, but you no longer need to clone this repository just to start the server.\n> You'll also require an instance of docker running.\n> ```bash\n> git clone https://github.com/alibaba/OpenSandbox.git\n> cd OpenSandbox/server\n> uv sync\n> cp example.config.toml ~/.sandbox.toml # Copy configuration file\n> uv run python -m src.main # Start the service\n> ```\n\n#### 2. Start the Sandbox Server\n\n```bash\nopensandbox-server\n\n# Show help\nopensandbox-server -h\n```\n\n#### 3. Create a Code Interpreter and Execute Commands\n\nInstall the Code Interpreter SDK\n\n```bash\nuv pip install opensandbox-code-interpreter\n```\n\nCreate a sandbox and execute commands\n\n```python\nimport asyncio\nfrom datetime import timedelta\n\nfrom code_interpreter import CodeInterpreter, SupportedLanguage\nfrom opensandbox import Sandbox\nfrom opensandbox.models import WriteEntry\n\nasync def main() -> None:\n # 1. Create a sandbox\n sandbox = await Sandbox.create(\n \"opensandbox/code-interpreter:v1.0.2\",\n entrypoint=[\"/opt/opensandbox/code-interpreter.sh\"],\n env={\"PYTHON_VERSION\": \"3.11\"},\n timeout=timedelta(minutes=10),\n )\n\n async with sandbox:\n\n # 2. Execute a shell command\n execution = await sandbox.commands.run(\"echo 'Hello OpenSandbox!'\")\n print(execution.logs.stdout[0].text)\n\n # 3. Write a file\n await sandbox.files.write_files([\n WriteEntry(path=\"/tmp/hello.txt\", data=\"Hello World\", mode=644)\n ])\n\n # 4. Read a file\n content = await sandbox.files.read_file(\"/tmp/hello.txt\")\n print(f\"Content: {content}\") # Content: Hello World\n\n # 5. Create a code interpreter\n interpreter = await CodeInterpreter.create(sandbox)\n\n # 6. Execute Python code (single-run, pass language directly)\n result = await interpreter.codes.run(\n \"\"\"\n import sys\n print(sys.version)\n result = 2 + 2\n result\n \"\"\",\n language=SupportedLanguage.PYTHON,\n )\n\n print(result.result[0].text) # 4\n print(result.logs.stdout[0].text) # 3.11.14\n\n # 7. Cleanup the sandbox\n await sandbox.kill()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### More Examples\n\nOpenSandbox provides examples covering SDK usage, agent integrations, browser automation, and training workloads. All example code is located in the `examples/` directory.\n\n#### ๐ŸŽฏ Basic Examples\n\n- **[code-interpreter](examples/code-interpreter/README.md)** - End-to-end Code Interpreter SDK workflow in a sandbox.\n- **[aio-sandbox](examples/aio-sandbox/README.md)** - All-in-One sandbox setup using the OpenSandbox SDK.\n- **[agent-sandbox](examples/agent-sandbox/README.md)** - Example integration for running OpenSandbox workloads on Kubernetes with [kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox).\n\n#### ๐Ÿค– Coding Agent Integrations\n\n- **[claude-code](examples/claude-code/README.md)** - Run Claude Code inside OpenSandbox.\n- **[gemini-cli](examples/gemini-cli/README.md)** - Run Google Gemini CLI inside OpenSandbox.\n- **[codex-cli](examples/codex-cli/README.md)** - Run OpenAI Codex CLI inside OpenSandbox.\n- **[kimi-cli](examples/kimi-cli/README.md)** - Run [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) (Moonshot AI) inside OpenSandbox.\n- **[langgraph](examples/langgraph/README.md)** - LangGraph state-machine workflow that creates/runs a sandbox job with fallback retry.\n- **[google-adk](examples/google-adk/README.md)** - Google ADK agent using OpenSandbox tools to write/read files and run commands.\n- **[nullclaw](examples/nullclaw/README.md)** - Launch a [Nullclaw](https://github.com/nullclaw/nullclaw) Gateway inside a sandbox.\n- **[openclaw](examples/openclaw/README.md)** - Launch an OpenClaw Gateway inside a sandbox.\n\n#### ๐ŸŒ Browser and Desktop Environments\n\n- **[chrome](examples/chrome/README.md)** - Chromium sandbox with VNC and DevTools access for automation and debugging.\n- **[playwright](examples/playwright/README.md)** - Playwright + Chromium headless scraping and testing example.\n- **[desktop](examples/desktop/README.md)** - Full desktop environment in a sandbox with VNC access.\n- **[vscode](examples/vscode/README.md)** - code-server (VS Code Web) running inside a sandbox for remote dev.\n\n#### ๐Ÿง  ML and Training\n\n- **[rl-training](examples/rl-training/README.md)** - DQN CartPole training in a sandbox with checkpoints and summary output.\n\nFor more details, please refer to [examples](examples/README.md) and the README files in each example directory.\n\n## Project Structure\n\n| Directory | Description |\n|-----------|------------------------------------------------------------------|\n| [`sdks/`](sdks/) | Multi-language SDKs (Python, Java/Kotlin, TypeScript/JavaScript, C#/.NET) |\n| [`specs/`](specs/README.md) | OpenAPI specs and lifecycle specifications |\n| [`server/`](server/README.md) | Python FastAPI sandbox lifecycle server |\n| [`kubernetes/`](kubernetes/README.md) | Kubernetes deployment and examples |\n| [`components/execd/`](components/execd/README.md) | Sandbox execution daemon (commands and file operations) |\n| [`components/ingress/`](components/ingress/README.md) | Sandbox traffic ingress proxy |\n| [`components/egress/`](components/egress/README.md) | Sandbox network egress control |\n| [`sandboxes/`](sandboxes/) | Runtime sandbox implementations |\n| [`examples/`](examples/README.md) | Integration examples and use cases |\n| [`oseps/`](oseps/README.md) | OpenSandbox Enhancement Proposals |\n| [`docs/`](docs/) | Architecture and design documentation |\n| [`tests/`](tests/) | Cross-component E2E tests |\n| [`scripts/`](scripts/) | Development and maintenance scripts |\n\nFor detailed architecture, see [docs/architecture.md](docs/architecture.md).\n\n## Documentation\n\n- [docs/architecture.md](docs/architecture.md) โ€“ Overall architecture & design philosophy\n- [oseps/README.md](oseps/README.md) โ€“ OpenSandbox Enhancement Proposals\n- SDK\n - Sandbox base SDK ([Java/Kotlin SDK](sdks/sandbox/kotlin/README.md), [Python SDK](sdks/sandbox/python/README.md), [JavaScript/TypeScript SDK](sdks/sandbox/javascript/README.md), [C#/.NET SDK](sdks/sandbox/csharp/README.md)) - includes sandbox lifecycle, command execution, file operations\n - Code Interpreter SDK ([Java/Kotlin SDK](sdks/code-interpreter/kotlin/README.md), [Python SDK](sdks/code-interpreter/python/README.md), [JavaScript/TypeScript SDK](sdks/code-interpreter/javascript/README.md), [C#/.NET SDK](sdks/code-interpreter/csharp/README.md)) - code interpreter\n- [specs/README.md](specs/README.md) - OpenAPI definitions for sandbox lifecycle API and sandbox execution API\n- [server/README.md](server/README.md) - Sandbox server startup and configuration; supports Docker and Kubernetes runtimes\n\n## License\n\nThis project is open source under the [Apache 2.0 License](LICENSE).\n\n## Roadmap [2026.03]\n\n### SDK\n\n- **Sandbox client connection pool** - Client-side sandbox connection pool management, providing pre-provisioned sandboxes to obtain an environment at X ms.\n- **Go SDK** - Go client SDK for sandbox lifecycle management, command execution, and file operations.\n\n### Sandbox Runtime\n\n- **Persistent volumes** - Mountable persistent volumes for sandboxes (see [Proposal 0003](oseps/0003-volume-and-volumebinding-support.md)).\n- **Local lightweight sandbox** - Lightweight sandbox for AI tools running directly on PCs.\n- **Secure Container** - Secure sandbox for AI Agents running inside container.\n\n### Deployment\n\n- **Guide** - Deployment guide for self-hosted Kubernetes cluster.\n\n## Contact and Discussion\n\n- Issues: Submit bugs, feature requests, or design discussions through GitHub Issues\n- DingTalk: Join the [OpenSandbox technical discussion group](https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=&_dt_no_comment=1&origin=11)\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=alibaba/OpenSandbox&type=date&legend=top-left)](https://www.star-history.com/#alibaba/OpenSandbox&type=date&legend=top-left)\n" }, { "path": "SECURITY.md", "content": "# Security Policy\n\n## Reporting Security Issues\n\nThe OpenSandbox team takes security seriously. If you discover a security vulnerability, please report it responsibly.\n\n### How to Report\n\n- **GitHub Security Advisories**: Open a private security advisory on GitHub\n- **Email**: Contact the maintainers directly with \"[SECURITY]\" in the subject\n\n### What to Include\n\n- Clear description of the vulnerability\n- Steps to reproduce\n- Potential impact and scope\n- Suggested remediation (if available)\n\n## Response Process\n\n1. Acknowledgment within 48 hours\n2. Investigation and validation\n3. Fix development and testing\n4. Coordinated disclosure\n\n## Supported Versions\n\nOnly the latest release and main branch are actively supported with security updates.\n\n## Security Best Practices\n\nWhen deploying OpenSandbox:\n- Keep dependencies up to date\n- Use network policies to restrict sandbox egress\n- Monitor audit logs regularly\n- Follow principle of least privilege\n" }, { "path": "cli/README.md", "content": "# OpenSandbox CLI\n\nA command-line interface for managing OpenSandbox environments from your terminal. Built on top of the [OpenSandbox Python SDK](../sdks/sandbox/python/README.md), the CLI provides intuitive commands for sandbox lifecycle management, file operations, command execution, and code interpretation.\n\n## Installation\n\n### pip\n\n```bash\npip install opensandbox-cli\n```\n\n### uv\n\n```bash\nuv add opensandbox-cli\n```\n\n### pipx (recommended for global CLI usage)\n\n```bash\npipx install opensandbox-cli\n```\n\n## Overview\n\n```bash\nosb --help\n```\n\n![CLI Help](assets/cli_help.png)\n\n## Quick Start\n\n### Step 0: Start the OpenSandbox Server\n\nBefore using the CLI, make sure the OpenSandbox server is running. See the root [README.md](../README.md) for startup instructions.\n\n```bash\nopensandbox-server\n```\n\n![Start OpenSandbox Server](assets/start_opensandbox_server.png)\n\n### Step 1: Install the CLI\n\n```bash\ncd cli\nuv pip install -e .\n```\n\n![Install CLI](assets/install_cli.png)\n\n### Step 2: Initialize Configuration\n\n```bash\nosb config init\nosb config set connection.domain localhost:8080\nosb config set connection.protocol http\n```\n\n![Init CLI](assets/init_cli.png)\n\n### Step 3: Create a Sandbox\n\n```bash\nosb sandbox create --image python:3.12\n```\n\n![Create Sandbox](assets/cli_create_sandbox.png)\n\n### Step 4: List Sandboxes\n\n```bash\n# Table output (default)\nosb sandbox list\n\n# JSON output for scripting\nosb -o json sandbox list\n```\n\n![List Sandboxes](assets/cli_list_sandbox.png)\n\n![List Sandboxes JSON](assets/cli_list_sandbox_json.png)\n\n### Short ID Matching\n\nLike Docker, you don't need to type the full sandbox ID โ€” just enough characters to uniquely identify the target sandbox:\n\n```bash\n# Full ID\nosb sandbox get db027570-4f86-45f8-b1a8-c31a2dd90da8\n\n# Short prefix โ€” as long as it's unambiguous\nosb sandbox get db02\nosb exec db02 -- echo \"hello\"\n```\n\nIf the prefix matches multiple sandboxes, the CLI will report an error listing the matches so you can be more specific.\n\n![Short ID Matching](assets/cli_sandbox_search.png)\n\n### Step 5: Execute Commands\n\n```bash\nosb exec -- echo \"hello world\"\nosb exec -- python -c \"print(1+1)\"\n```\n\n![Execute Commands](assets/cli_sandbox_exec.png)\n\n### Step 6: File Operations\n\n```bash\n# Write a file\nosb file write /tmp/test.txt -c \"hello\"\n\n# Read it back\nosb file cat /tmp/test.txt\n```\n\n![File Operations](assets/cli_sandbox_file.png)\n\n### Step 7: Cleanup\n\n```bash\nosb sandbox kill \nosb sandbox list\n```\n\n![Kill Sandbox](assets/cli_kill_sandbox.png)\n\n## Command Reference\n\n### `osb sandbox` โ€” Lifecycle Management\n\n| Command | Description |\n| ---------- | ------------------------------------------- |\n| `create` | Create a new sandbox |\n| `list` | List sandboxes (with optional filters) |\n| `get` | Get sandbox details by ID |\n| `kill` | Terminate one or more sandboxes |\n| `pause` | Pause a running sandbox |\n| `resume` | Resume a paused sandbox |\n| `renew` | Renew sandbox expiration |\n| `endpoint` | Get public endpoint for a sandbox port |\n| `health` | Check sandbox health |\n| `metrics` | Get sandbox resource metrics (CPU, memory) |\n\n### `osb command` โ€” Command Execution\n\n| Command | Description |\n| ----------- | ----------------------------------------- |\n| `run` | Run a shell command in the sandbox |\n| `status` | Get command execution status |\n| `logs` | Get background command logs |\n| `interrupt` | Interrupt a running command |\n\n### `osb exec` โ€” Quick Command Shortcut\n\n```bash\nosb exec -- \n```\n\nShortcut for `osb command run`. Everything after `--` is passed as the command.\n\n### `osb file` โ€” File Operations\n\n| Command | Description |\n| ---------- | ------------------------------------------ |\n| `cat` | Read file contents |\n| `write` | Write content to a file |\n| `upload` | Upload a local file to the sandbox |\n| `download` | Download a file from the sandbox |\n| `rm` | Delete files |\n| `mv` | Move or rename a file |\n| `mkdir` | Create directories |\n| `rmdir` | Remove directories |\n| `search` | Search for files by pattern |\n| `info` | Get file/directory metadata |\n| `chmod` | Set file permissions |\n| `replace` | Find and replace content in a file |\n\n### `osb code` โ€” Code Interpreter\n\n| Command | Description |\n| ----------- | ----------------------------------------- |\n| `run` | Execute code in a sandbox |\n| `context` | Manage code execution contexts |\n| `interrupt` | Interrupt a running code execution |\n\n### `osb config` โ€” Configuration\n\n| Command | Description |\n| ------- | ------------------------------------------ |\n| `init` | Create a default config file |\n| `show` | Show resolved configuration |\n\n## Configuration\n\nThe CLI resolves configuration from multiple sources with the following priority (highest to lowest):\n\n1. **CLI flags** โ€” `--api-key`, `--domain`, `--protocol`, `--timeout`\n2. **Environment variables** โ€” `OPEN_SANDBOX_API_KEY`, `OPEN_SANDBOX_DOMAIN`, `OPEN_SANDBOX_PROTOCOL`, `OPEN_SANDBOX_REQUEST_TIMEOUT`, `OPEN_SANDBOX_OUTPUT`\n3. **Config file** โ€” `~/.opensandbox/config.toml` (or path specified via `--config`)\n4. **SDK defaults**\n\n### Config File Format\n\n```toml\n[connection]\napi_key = \"your-api-key\"\ndomain = \"localhost:8080\"\nprotocol = \"http\"\nrequest_timeout = 30\n\n[output]\nformat = \"table\" # table | json | yaml\ncolor = true\n\n[defaults]\nimage = \"python:3.11\"\ntimeout = \"10m\"\n```\n\n## Global Options\n\n| Option | Description |\n| ----------------------------- | -------------------------------- |\n| `--api-key TEXT` | API key for authentication |\n| `--domain TEXT` | API server domain |\n| `--protocol [http\\|https]` | Protocol |\n| `--timeout INTEGER` | Request timeout in seconds |\n| `-o, --output [table\\|json\\|yaml]` | Output format |\n| `--config PATH` | Config file path |\n| `-v, --verbose` | Enable debug output |\n| `--no-color` | Disable colored output |\n| `--version` | Show version |\n\n## Output Formats\n\nThe CLI supports three output formats via the `-o` / `--output` flag:\n\n- **`table`** (default) โ€” Human-friendly tables powered by [Rich](https://github.com/Textualize/rich)\n- **`json`** โ€” Machine-readable JSON\n- **`yaml`** โ€” YAML output\n\n```bash\n# Table (default)\nosb sandbox list\n\n# JSON for scripting\nosb -o json sandbox list\n\n# YAML\nosb -o yaml sandbox list\n```\n" }, { "path": "cli/pyproject.toml", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n[build-system]\nrequires = [\"hatchling\", \"hatch-vcs\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"opensandbox-cli\"\ndynamic = [\"version\"]\ndescription = \"OpenSandbox CLI - Command-line interface for managing sandboxes\"\nauthors = [\n { name = \"OpenSandbox Team\", email = \"ninan.nn@alibaba-inc.com\" }\n]\nlicense = { file = \"LICENSE\" }\nreadme = \"README.md\"\nrequires-python = \">=3.10\"\nkeywords = [\"sandbox\", \"cli\", \"opensandbox\"]\nclassifiers = [\n \"Development Status :: 3 - Alpha\",\n \"Intended Audience :: Developers\",\n \"License :: OSI Approved :: Apache Software License\",\n \"Operating System :: OS Independent\",\n \"Programming Language :: Python :: 3\",\n \"Programming Language :: Python :: 3 :: Only\",\n \"Programming Language :: Python :: 3.10\",\n \"Programming Language :: Python :: 3.11\",\n \"Programming Language :: Python :: 3.12\",\n \"Programming Language :: Python :: 3.13\",\n \"Topic :: Software Development :: Libraries\",\n]\ndependencies = [\n \"opensandbox>=0.1.4,<0.2.0\",\n \"opensandbox-code-interpreter>=0.1.0,<0.2.0\",\n \"click>=8.1.0,<9.0\",\n \"rich>=13.0.0,<14.0\",\n \"pyyaml>=6.0,<7.0\",\n \"tomli>=2.0.0; python_version < '3.11'\",\n]\n\n[project.urls]\nHomepage = \"https://open-sandbox.ai\"\nRepository = \"https://github.com/alibaba/OpenSandbox\"\nDocumentation = \"https://open-sandbox.ai\"\nIssues = \"https://github.com/alibaba/OpenSandbox/issues\"\n\n[project.scripts]\nopensandbox = \"opensandbox_cli.main:cli\"\nosb = \"opensandbox_cli.main:cli\"\n\n[tool.hatch.version]\nsource = \"vcs\"\n\n[tool.hatch.version.raw-options]\nroot = \"..\"\ntag_regex = \"^python/cli/v(?P\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:[\\\\.\\\\w\\\\+\\\\-]*)?)$\"\ngit_describe_command = 'git describe --dirty --tags --long --match \"python/cli/v*\"'\nfallback_version = \"0.1.0\"\n\n[tool.hatch.build]\ninclude = [\n \"LICENSE\",\n \"src/**/py.typed\",\n \"src/opensandbox_cli\",\n]\n\n[tool.hatch.build.targets.wheel]\npackages = [\"src/opensandbox_cli\"]\n\n[dependency-groups]\ndev = [\n \"pytest>=7.0.0\",\n \"pytest-cov>=4.0.0\",\n \"ruff>=0.14.8\",\n \"pyright>=1.1.0\",\n]\n\n[tool.ruff]\ntarget-version = \"py310\"\nline-length = 88\n\n[tool.ruff.lint]\nselect = [\n \"E\", # pycodestyle errors\n \"W\", # pycodestyle warnings\n \"F\", # pyflakes\n \"I\", # isort\n \"B\", # flake8-bugbear\n \"C4\", # flake8-comprehensions\n \"UP\", # pyupgrade\n]\nignore = [\n \"E501\", # line too long, handled by formatter\n \"B008\", # do not perform function calls in argument defaults\n \"C901\", # too complex\n]\n\n[tool.ruff.lint.per-file-ignores]\n\"__init__.py\" = [\"F401\"]\n\n[tool.pyright]\ntypeCheckingMode = \"standard\"\npythonVersion = \"3.10\"\npythonPlatform = \"All\"\ninclude = [\"src\"]\nexclude = [\n \"**/node_modules\",\n \"**/__pycache__\",\n]\nreportMissingImports = true\nreportMissingTypeStubs = false\n\n[tool.pytest.ini_options]\nminversion = \"6.0\"\naddopts = \"-ra -q --strict-markers --strict-config\"\ntestpaths = [\"tests\"]\npython_files = [\"test_*.py\", \"*_test.py\"]\n\n[tool.coverage.run]\nsource = [\"src\"]\nbranch = true\n\n[tool.uv.sources]\nopensandbox = { path = \"../sdks/sandbox/python\", editable = true }\nopensandbox-code-interpreter = { path = \"../sdks/code-interpreter/python\", editable = true }\n" }, { "path": "cli/src/opensandbox_cli/__init__.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\ntry:\n from importlib.metadata import version\n\n __version__ = version(\"opensandbox-cli\")\nexcept Exception:\n __version__ = \"0.0.0-dev\"\n" }, { "path": "cli/src/opensandbox_cli/__main__.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Allow running as ``python -m opensandbox_cli``.\"\"\"\n\nfrom opensandbox_cli.main import cli\n\nif __name__ == \"__main__\":\n cli()\n" }, { "path": "cli/src/opensandbox_cli/client.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"SDK client factory stored in Click context.\"\"\"\n\nfrom __future__ import annotations\n\nimport re\nfrom dataclasses import dataclass, field\nfrom datetime import timedelta\nfrom typing import Any\n\nimport click\n\nfrom opensandbox.config.connection_sync import ConnectionConfigSync\nfrom opensandbox.models.sandboxes import SandboxFilter\nfrom opensandbox.sync.manager import SandboxManagerSync\nfrom opensandbox.sync.sandbox import SandboxSync\n\nfrom opensandbox_cli.output import OutputFormatter\n\n# Full UUID pattern: 8-4-4-4-12 hex characters\n_UUID_RE = re.compile(\n r\"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$\"\n)\n\n\n@dataclass\nclass ClientContext:\n \"\"\"Shared context passed via ``ctx.obj`` to all Click commands.\"\"\"\n\n resolved_config: dict[str, Any]\n output: OutputFormatter\n _connection_config: ConnectionConfigSync | None = field(\n default=None, init=False, repr=False\n )\n _manager: SandboxManagerSync | None = field(\n default=None, init=False, repr=False\n )\n\n @property\n def connection_config(self) -> ConnectionConfigSync:\n if self._connection_config is None:\n cfg = self.resolved_config\n self._connection_config = ConnectionConfigSync(\n api_key=cfg.get(\"api_key\"),\n domain=cfg.get(\"domain\"),\n protocol=cfg.get(\"protocol\", \"http\"),\n request_timeout=timedelta(seconds=cfg.get(\"request_timeout\", 30)),\n )\n return self._connection_config\n\n def get_manager(self) -> SandboxManagerSync:\n \"\"\"Return a lazily-created ``SandboxManagerSync``.\"\"\"\n if self._manager is None:\n self._manager = SandboxManagerSync.create(self.connection_config)\n return self._manager\n\n def resolve_sandbox_id(self, prefix: str) -> str:\n \"\"\"Resolve a sandbox ID prefix to the full ID (Docker-style).\n\n If *prefix* looks like a complete UUID, it is returned as-is without\n querying the server. Otherwise **all pages** of sandboxes are fetched\n so that prefix collisions on later pages are never missed.\n \"\"\"\n # Skip resolution for full UUIDs\n if _UUID_RE.match(prefix):\n return prefix\n\n mgr = self.get_manager()\n matches: list[str] = []\n page = 0\n\n while True:\n result = mgr.list_sandbox_infos(\n SandboxFilter(page=page, page_size=100)\n )\n if result.sandbox_infos:\n matches.extend(\n info.id\n for info in result.sandbox_infos\n if info.id.startswith(prefix)\n )\n # Stop early if we already found >1 match (ambiguous)\n if len(matches) > 1:\n break\n if not result.pagination.has_next_page:\n break\n page += 1\n\n if len(matches) == 1:\n return matches[0]\n elif len(matches) == 0:\n raise click.ClickException(\n f\"No sandbox found with ID prefix '{prefix}'\"\n )\n else:\n ids_str = \", \".join(matches[:5])\n if len(matches) > 5:\n ids_str += \", ...\"\n raise click.ClickException(\n f\"Ambiguous ID prefix '{prefix}' matches {len(matches)} sandboxes: {ids_str}\"\n )\n\n def connect_sandbox(\n self, sandbox_id: str, *, skip_health_check: bool = True\n ) -> SandboxSync:\n \"\"\"Connect to an existing sandbox by ID (supports prefix matching).\"\"\"\n sandbox_id = self.resolve_sandbox_id(sandbox_id)\n return SandboxSync.connect(\n sandbox_id,\n connection_config=self.connection_config,\n skip_health_check=skip_health_check,\n )\n\n def close(self) -> None:\n \"\"\"Release resources.\"\"\"\n if self._manager is not None:\n self._manager.close()\n self._manager = None\n if self._connection_config is not None:\n self._connection_config.close_transport_if_owned()\n self._connection_config = None\n" }, { "path": "cli/src/opensandbox_cli/commands/__init__.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n" }, { "path": "cli/src/opensandbox_cli/commands/code.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Code execution commands: run, context management, interrupt.\"\"\"\n\nfrom __future__ import annotations\n\nimport sys\n\nimport click\n\nfrom opensandbox.models.execd import OutputMessage\nfrom opensandbox.models.execd_sync import ExecutionHandlersSync\n\nfrom opensandbox_cli.client import ClientContext\nfrom opensandbox_cli.utils import handle_errors\n\n\n@click.group(\"code\", invoke_without_command=True)\n@click.pass_context\ndef code_group(ctx: click.Context) -> None:\n \"\"\"๐Ÿ’ป Execute code in a sandbox (via Code Interpreter).\"\"\"\n if ctx.invoked_subcommand is None:\n click.echo(ctx.get_help())\n\n\n# ---- run ------------------------------------------------------------------\n\n@code_group.command(\"run\")\n@click.argument(\"sandbox_id\")\n@click.option(\"--language\", \"-l\", required=True, help=\"Language (python, javascript, java, go, bash, ...).\")\n@click.option(\"--code\", \"-c\", default=None, help=\"Code to execute. Reads from stdin if not provided.\")\n@click.option(\"--context-id\", default=None, help=\"Execution context ID for stateful sessions.\")\n@click.pass_obj\n@handle_errors\ndef code_run(\n obj: ClientContext,\n sandbox_id: str,\n language: str,\n code: str | None,\n context_id: str | None,\n) -> None:\n \"\"\"Execute code in a sandbox.\"\"\"\n from code_interpreter.sync.code_interpreter import CodeInterpreterSync\n\n if code is None:\n if sys.stdin.isatty():\n click.echo(\"Reading code from stdin (Ctrl+D to finish):\", err=True)\n code = sys.stdin.read()\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n interpreter = CodeInterpreterSync.create(sandbox)\n\n kwargs: dict = {}\n if context_id:\n ctx = interpreter.codes.get_context(context_id)\n kwargs[\"context\"] = ctx\n\n def on_stdout(msg: OutputMessage) -> None:\n sys.stdout.write(msg.text)\n sys.stdout.flush()\n\n def on_stderr(msg: OutputMessage) -> None:\n sys.stderr.write(msg.text)\n sys.stderr.flush()\n\n handlers = ExecutionHandlersSync(on_stdout=on_stdout, on_stderr=on_stderr)\n execution = interpreter.codes.run(\n code, language=language, handlers=handlers, **kwargs\n )\n\n if execution.error:\n obj.output.error(\n f\"{execution.error.name}: {execution.error.value}\"\n )\n sys.exit(1)\n finally:\n sandbox.close()\n\n\n# ---- context group --------------------------------------------------------\n\n@code_group.group(\"context\", invoke_without_command=True)\n@click.pass_context\ndef context_group(ctx: click.Context) -> None:\n \"\"\"Manage code execution contexts.\"\"\"\n if ctx.invoked_subcommand is None:\n click.echo(ctx.get_help())\n\n\n@context_group.command(\"create\")\n@click.argument(\"sandbox_id\")\n@click.option(\"--language\", \"-l\", required=True, help=\"Language for the context.\")\n@click.pass_obj\n@handle_errors\ndef context_create(obj: ClientContext, sandbox_id: str, language: str) -> None:\n \"\"\"Create a new code execution context.\"\"\"\n from code_interpreter.sync.code_interpreter import CodeInterpreterSync\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n interpreter = CodeInterpreterSync.create(sandbox)\n ctx = interpreter.codes.create_context(language)\n obj.output.success_panel(\n {\"context_id\": ctx.id, \"language\": language},\n title=\"Context Created\",\n )\n finally:\n sandbox.close()\n\n\n@context_group.command(\"list\")\n@click.argument(\"sandbox_id\")\n@click.option(\"--language\", \"-l\", required=True, help=\"Language to list contexts for.\")\n@click.pass_obj\n@handle_errors\ndef context_list(obj: ClientContext, sandbox_id: str, language: str) -> None:\n \"\"\"List code execution contexts.\"\"\"\n from code_interpreter.sync.code_interpreter import CodeInterpreterSync\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n interpreter = CodeInterpreterSync.create(sandbox)\n contexts = interpreter.codes.list_contexts(language)\n for ctx in contexts:\n click.echo(f\"{ctx.id}\")\n finally:\n sandbox.close()\n\n\n@context_group.command(\"delete\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"context_id\")\n@click.pass_obj\n@handle_errors\ndef context_delete(obj: ClientContext, sandbox_id: str, context_id: str) -> None:\n \"\"\"Delete a code execution context.\"\"\"\n from code_interpreter.sync.code_interpreter import CodeInterpreterSync\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n interpreter = CodeInterpreterSync.create(sandbox)\n interpreter.codes.delete_context(context_id)\n obj.output.success(f\"Deleted context: {context_id}\")\n finally:\n sandbox.close()\n\n\n@context_group.command(\"delete-all\")\n@click.argument(\"sandbox_id\")\n@click.option(\"--language\", \"-l\", required=True, help=\"Language to delete all contexts for.\")\n@click.pass_obj\n@handle_errors\ndef context_delete_all(obj: ClientContext, sandbox_id: str, language: str) -> None:\n \"\"\"Delete all code execution contexts for a language.\"\"\"\n from code_interpreter.sync.code_interpreter import CodeInterpreterSync\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n interpreter = CodeInterpreterSync.create(sandbox)\n interpreter.codes.delete_contexts(language)\n obj.output.success(f\"Deleted all {language} contexts\")\n finally:\n sandbox.close()\n\n\n# ---- interrupt ------------------------------------------------------------\n\n@code_group.command(\"interrupt\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"execution_id\")\n@click.pass_obj\n@handle_errors\ndef code_interrupt(obj: ClientContext, sandbox_id: str, execution_id: str) -> None:\n \"\"\"Interrupt a running code execution.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n sandbox.commands.interrupt(execution_id)\n obj.output.success(f\"Interrupted: {execution_id}\")\n finally:\n sandbox.close()\n" }, { "path": "cli/src/opensandbox_cli/commands/command.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Command execution commands: run, status, logs, interrupt + top-level exec alias.\"\"\"\n\nfrom __future__ import annotations\n\nimport shlex\nimport sys\nfrom datetime import timedelta\n\nimport click\n\nfrom opensandbox.models.execd import OutputMessage, RunCommandOpts\nfrom opensandbox.models.execd_sync import ExecutionHandlersSync\n\nfrom opensandbox_cli.client import ClientContext\nfrom opensandbox_cli.utils import DURATION, handle_errors\n\n\n@click.group(\"command\", invoke_without_command=True)\n@click.pass_context\ndef command_group(ctx: click.Context) -> None:\n \"\"\"โšก Execute commands in a sandbox.\"\"\"\n if ctx.invoked_subcommand is None:\n click.echo(ctx.get_help())\n\n\n# ---- run ------------------------------------------------------------------\n\ndef _run_command(\n obj: ClientContext,\n sandbox_id: str,\n command: tuple[str, ...],\n background: bool,\n workdir: str | None,\n timeout: timedelta | None,\n) -> None:\n \"\"\"Shared implementation for 'command run' and top-level 'exec'.\"\"\"\n cmd_str = \" \".join(shlex.quote(arg) for arg in command)\n sandbox = obj.connect_sandbox(sandbox_id)\n\n try:\n opts = RunCommandOpts(\n background=background,\n working_directory=workdir,\n timeout=timeout,\n )\n\n if background:\n execution = sandbox.commands.run(cmd_str, opts=opts)\n obj.output.success_panel(\n {\n \"execution_id\": execution.id,\n \"sandbox_id\": sandbox_id,\n \"mode\": \"background\",\n },\n title=\"Background Command Started\",\n )\n return\n\n # Foreground: stream stdout/stderr to terminal\n last_text = \"\"\n\n def on_stdout(msg: OutputMessage) -> None:\n nonlocal last_text\n last_text = msg.text\n sys.stdout.write(msg.text)\n sys.stdout.flush()\n\n def on_stderr(msg: OutputMessage) -> None:\n nonlocal last_text\n last_text = msg.text\n sys.stderr.write(msg.text)\n sys.stderr.flush()\n\n handlers = ExecutionHandlersSync(on_stdout=on_stdout, on_stderr=on_stderr)\n execution = sandbox.commands.run(cmd_str, opts=opts, handlers=handlers)\n\n # Ensure terminal prompt starts on a new line\n if last_text and not last_text.endswith(\"\\n\"):\n sys.stdout.write(\"\\n\")\n sys.stdout.flush()\n\n if execution.error:\n obj.output.error_panel(\n f\"{execution.error.name}: {execution.error.value}\",\n title=\"Execution Error\",\n )\n sys.exit(1)\n finally:\n sandbox.close()\n\n\n@command_group.command(\"run\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"command\", nargs=-1, required=True)\n@click.option(\"-d\", \"--background\", is_flag=True, default=False, help=\"Run in background.\")\n@click.option(\"-w\", \"--workdir\", default=None, help=\"Working directory.\")\n@click.option(\"-t\", \"--timeout\", type=DURATION, default=None, help=\"Command timeout (e.g. 30s, 5m).\")\n@click.pass_obj\n@handle_errors\ndef command_run(\n obj: ClientContext,\n sandbox_id: str,\n command: tuple[str, ...],\n background: bool,\n workdir: str | None,\n timeout: timedelta | None,\n) -> None:\n \"\"\"Run a command in a sandbox.\"\"\"\n _run_command(obj, sandbox_id, command, background, workdir, timeout)\n\n\n# ---- status ---------------------------------------------------------------\n\n@command_group.command(\"status\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"execution_id\")\n@click.pass_obj\n@handle_errors\ndef command_status(obj: ClientContext, sandbox_id: str, execution_id: str) -> None:\n \"\"\"Get command execution status.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n status = sandbox.commands.get_command_status(execution_id)\n obj.output.print_model(status, title=\"Command Status\")\n finally:\n sandbox.close()\n\n\n# ---- logs -----------------------------------------------------------------\n\n@command_group.command(\"logs\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"execution_id\")\n@click.option(\"--cursor\", type=int, default=None, help=\"Cursor for incremental reads.\")\n@click.pass_obj\n@handle_errors\ndef command_logs(\n obj: ClientContext, sandbox_id: str, execution_id: str, cursor: int | None\n) -> None:\n \"\"\"Get background command logs.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n logs = sandbox.commands.get_background_command_logs(execution_id, cursor=cursor)\n if obj.output.fmt in (\"json\", \"yaml\"):\n obj.output.print_model(logs, title=\"Command Logs\")\n else:\n click.echo(logs.content)\n finally:\n sandbox.close()\n\n\n# ---- interrupt ------------------------------------------------------------\n\n@command_group.command(\"interrupt\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"execution_id\")\n@click.pass_obj\n@handle_errors\ndef command_interrupt(obj: ClientContext, sandbox_id: str, execution_id: str) -> None:\n \"\"\"Interrupt a running command.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n sandbox.commands.interrupt(execution_id)\n obj.output.success(f\"Interrupted: {execution_id}\")\n finally:\n sandbox.close()\n\n\n# ---- top-level exec alias ------------------------------------------------\n\n@click.command(\"exec\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"command\", nargs=-1, required=True)\n@click.option(\"-d\", \"--background\", is_flag=True, default=False, help=\"Run in background.\")\n@click.option(\"-w\", \"--workdir\", default=None, help=\"Working directory.\")\n@click.option(\"-t\", \"--timeout\", type=DURATION, default=None, help=\"Command timeout (e.g. 30s, 5m).\")\n@click.pass_obj\n@handle_errors\ndef exec_cmd(\n obj: ClientContext,\n sandbox_id: str,\n command: tuple[str, ...],\n background: bool,\n workdir: str | None,\n timeout: timedelta | None,\n) -> None:\n \"\"\"๐Ÿš€ Execute a command in a sandbox (shortcut for 'command run').\"\"\"\n _run_command(obj, sandbox_id, command, background, workdir, timeout)\n" }, { "path": "cli/src/opensandbox_cli/commands/config_cmd.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Config management commands: init, show, set.\"\"\"\n\nfrom __future__ import annotations\n\nfrom pathlib import Path\n\nimport click\n\nfrom opensandbox_cli.client import ClientContext\nfrom opensandbox_cli.config import DEFAULT_CONFIG_PATH, init_config_file\nfrom opensandbox_cli.utils import handle_errors\n\n\n@click.group(\"config\", invoke_without_command=True)\n@click.pass_context\ndef config_group(ctx: click.Context) -> None:\n \"\"\"โš™๏ธ Manage CLI configuration.\"\"\"\n if ctx.invoked_subcommand is None:\n click.echo(ctx.get_help())\n\n\n# ---- init -----------------------------------------------------------------\n\n@config_group.command(\"init\")\n@click.option(\"--force\", is_flag=True, default=False, help=\"Overwrite existing config file.\")\n@click.option(\"--path\", \"config_path\", type=click.Path(path_type=Path), default=None, help=\"Config file path.\")\n@handle_errors\ndef config_init(force: bool, config_path: Path | None) -> None:\n \"\"\"Create a default configuration file.\"\"\"\n # config_init doesn't have @click.pass_obj, get formatter from context\n ctx = click.get_current_context(silent=True)\n obj = getattr(ctx, \"obj\", None) if ctx else None\n output = getattr(obj, \"output\", None) if obj else None\n\n try:\n path = init_config_file(config_path, force=force)\n if output:\n output.success(f\"Config file created: {path}\")\n else:\n click.echo(f\"Config file created: {path}\")\n except FileExistsError as exc:\n if output:\n output.warning(str(exc))\n else:\n click.secho(str(exc), fg=\"yellow\", err=True)\n\n\n# ---- show -----------------------------------------------------------------\n\n@config_group.command(\"show\")\n@click.pass_obj\n@handle_errors\ndef config_show(obj: ClientContext) -> None:\n \"\"\"Show the resolved configuration.\"\"\"\n obj.output.print_dict(obj.resolved_config, title=\"Resolved Configuration\")\n\n\n# ---- set ------------------------------------------------------------------\n\n@config_group.command(\"set\")\n@click.argument(\"key\")\n@click.argument(\"value\")\n@click.option(\"--path\", \"config_path\", type=click.Path(path_type=Path), default=None, help=\"Config file path.\")\n@handle_errors\ndef config_set(key: str, value: str, config_path: Path | None) -> None:\n \"\"\"Set a configuration value (e.g. 'connection.domain' 'localhost:9090').\"\"\"\n path = config_path or DEFAULT_CONFIG_PATH\n if not path.exists():\n click.secho(f\"Config file not found: {path}. Run 'osb config init' first.\", fg=\"red\", err=True)\n return\n\n content = path.read_text()\n\n # Simple key replacement in TOML\n # Supports dotted keys like connection.domain\n parts = key.split(\".\", 1)\n if len(parts) == 2:\n section, field = parts\n # Try to find and update existing value\n import re\n\n section_pattern = rf\"(\\[{re.escape(section)}\\].*?)(?=\\n\\[|\\Z)\"\n section_match = re.search(section_pattern, content, re.DOTALL)\n\n # Infer TOML value type: bool > int > float > string\n def _toml_value(raw: str) -> str:\n if raw.lower() in (\"true\", \"false\"):\n return raw.lower()\n try:\n int(raw)\n return raw\n except ValueError:\n pass\n try:\n float(raw)\n return raw\n except ValueError:\n pass\n return f'\"{raw}\"'\n\n toml_val = _toml_value(value)\n\n if section_match:\n section_text = section_match.group(1)\n field_pattern = rf'^(#?\\s*{re.escape(field)}\\s*=\\s*).*$'\n field_match = re.search(field_pattern, section_text, re.MULTILINE)\n if field_match:\n new_line = f'{field} = {toml_val}'\n new_section = section_text[:field_match.start()] + new_line + section_text[field_match.end():]\n content = content[:section_match.start()] + new_section + content[section_match.end():]\n else:\n # Add field to section\n insert_pos = section_match.end()\n content = content[:insert_pos] + f'\\n{field} = {toml_val}' + content[insert_pos:]\n else:\n # Add new section\n content += f'\\n[{section}]\\n{field} = {toml_val}\\n'\n else:\n click.secho(\"Key must be in 'section.field' format (e.g. connection.domain).\", fg=\"red\", err=True)\n return\n\n path.write_text(content)\n\n # config_set doesn't have @click.pass_obj, get formatter from context\n ctx = click.get_current_context(silent=True)\n obj = getattr(ctx, \"obj\", None) if ctx else None\n output = getattr(obj, \"output\", None) if obj else None\n if output:\n output.success(f\"Set {key} = {value}\")\n else:\n click.echo(f\"Set {key} = {value}\")\n" }, { "path": "cli/src/opensandbox_cli/commands/file.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"File operation commands: cat, write, upload, download, rm, mv, mkdir, rmdir, search, info, chmod, replace.\"\"\"\n\nfrom __future__ import annotations\n\nimport sys\nfrom pathlib import Path\n\nimport click\n\nfrom opensandbox_cli.client import ClientContext\nfrom opensandbox_cli.utils import handle_errors\n\n\n@click.group(\"file\", invoke_without_command=True)\n@click.pass_context\ndef file_group(ctx: click.Context) -> None:\n \"\"\"๐Ÿ“ File operations on a sandbox.\"\"\"\n if ctx.invoked_subcommand is None:\n click.echo(ctx.get_help())\n\n\n# ---- cat (read) -----------------------------------------------------------\n\n@file_group.command(\"cat\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"path\")\n@click.option(\"--encoding\", default=\"utf-8\", help=\"File encoding.\")\n@click.pass_obj\n@handle_errors\ndef file_cat(obj: ClientContext, sandbox_id: str, path: str, encoding: str) -> None:\n \"\"\"Read a file from the sandbox.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n content = sandbox.files.read_file(path, encoding=encoding)\n click.echo(content, nl=False)\n finally:\n sandbox.close()\n\n\n# ---- write ----------------------------------------------------------------\n\n@file_group.command(\"write\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"path\")\n@click.option(\"--content\", \"-c\", default=None, help=\"Content to write. Reads from stdin if not provided.\")\n@click.option(\"--encoding\", default=\"utf-8\", help=\"File encoding.\")\n@click.option(\"--mode\", default=None, help=\"File permission mode (e.g. 0644).\")\n@click.option(\"--owner\", default=None, help=\"File owner.\")\n@click.option(\"--group\", default=None, help=\"File group.\")\n@click.pass_obj\n@handle_errors\ndef file_write(\n obj: ClientContext,\n sandbox_id: str,\n path: str,\n content: str | None,\n encoding: str,\n mode: str | None,\n owner: str | None,\n group: str | None,\n) -> None:\n \"\"\"Write content to a file in the sandbox.\"\"\"\n if content is None:\n if sys.stdin.isatty():\n click.echo(\"Reading from stdin (Ctrl+D to finish):\", err=True)\n content = sys.stdin.read()\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n kwargs: dict = {\"encoding\": encoding}\n if mode is not None:\n kwargs[\"mode\"] = mode\n if owner is not None:\n kwargs[\"owner\"] = owner\n if group is not None:\n kwargs[\"group\"] = group\n sandbox.files.write_file(path, content, **kwargs)\n obj.output.success(f\"Written: {path}\")\n finally:\n sandbox.close()\n\n\n# ---- upload ---------------------------------------------------------------\n\n@file_group.command(\"upload\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"local_path\", type=click.Path(exists=True))\n@click.argument(\"remote_path\")\n@click.pass_obj\n@handle_errors\ndef file_upload(\n obj: ClientContext, sandbox_id: str, local_path: str, remote_path: str\n) -> None:\n \"\"\"Upload a local file to the sandbox.\"\"\"\n data = Path(local_path).read_bytes()\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n sandbox.files.write_file(remote_path, data)\n obj.output.success(f\"Uploaded: {local_path} โ†’ {remote_path}\")\n finally:\n sandbox.close()\n\n\n# ---- download -------------------------------------------------------------\n\n@file_group.command(\"download\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"remote_path\")\n@click.argument(\"local_path\", type=click.Path())\n@click.pass_obj\n@handle_errors\ndef file_download(\n obj: ClientContext, sandbox_id: str, remote_path: str, local_path: str\n) -> None:\n \"\"\"Download a file from the sandbox to local disk.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n content = sandbox.files.read_bytes(remote_path)\n Path(local_path).write_bytes(content)\n obj.output.success(f\"Downloaded: {remote_path} โ†’ {local_path}\")\n finally:\n sandbox.close()\n\n\n# ---- rm (delete) ----------------------------------------------------------\n\n@file_group.command(\"rm\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"paths\", nargs=-1, required=True)\n@click.pass_obj\n@handle_errors\ndef file_rm(obj: ClientContext, sandbox_id: str, paths: tuple[str, ...]) -> None:\n \"\"\"Delete files from the sandbox.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n sandbox.files.delete_files(list(paths))\n for p in paths:\n obj.output.success(f\"Deleted: {p}\")\n finally:\n sandbox.close()\n\n\n# ---- mv (move) ------------------------------------------------------------\n\n@file_group.command(\"mv\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"source\")\n@click.argument(\"destination\")\n@click.pass_obj\n@handle_errors\ndef file_mv(\n obj: ClientContext, sandbox_id: str, source: str, destination: str\n) -> None:\n \"\"\"Move/rename a file in the sandbox.\"\"\"\n from opensandbox.models.filesystem import MoveEntry\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n sandbox.files.move_files([MoveEntry(source=source, destination=destination)])\n obj.output.success(f\"Moved: {source} โ†’ {destination}\")\n finally:\n sandbox.close()\n\n\n# ---- mkdir ----------------------------------------------------------------\n\n@file_group.command(\"mkdir\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"paths\", nargs=-1, required=True)\n@click.option(\"--mode\", default=None, help=\"Directory permission mode.\")\n@click.option(\"--owner\", default=None, help=\"Directory owner.\")\n@click.option(\"--group\", default=None, help=\"Directory group.\")\n@click.pass_obj\n@handle_errors\ndef file_mkdir(\n obj: ClientContext,\n sandbox_id: str,\n paths: tuple[str, ...],\n mode: str | None,\n owner: str | None,\n group: str | None,\n) -> None:\n \"\"\"Create directories in the sandbox.\"\"\"\n from opensandbox.models.filesystem import WriteEntry\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n entries = []\n for p in paths:\n kwargs: dict = {\"path\": p}\n if mode is not None:\n kwargs[\"mode\"] = mode\n if owner is not None:\n kwargs[\"owner\"] = owner\n if group is not None:\n kwargs[\"group\"] = group\n entries.append(WriteEntry(**kwargs))\n sandbox.files.create_directories(entries)\n for p in paths:\n obj.output.success(f\"Created: {p}\")\n finally:\n sandbox.close()\n\n\n# ---- rmdir ----------------------------------------------------------------\n\n@file_group.command(\"rmdir\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"paths\", nargs=-1, required=True)\n@click.pass_obj\n@handle_errors\ndef file_rmdir(obj: ClientContext, sandbox_id: str, paths: tuple[str, ...]) -> None:\n \"\"\"Delete directories from the sandbox.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n sandbox.files.delete_directories(list(paths))\n for p in paths:\n obj.output.success(f\"Removed: {p}\")\n finally:\n sandbox.close()\n\n\n# ---- search ---------------------------------------------------------------\n\n@file_group.command(\"search\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"path\")\n@click.option(\"--pattern\", \"-p\", required=True, help=\"Glob pattern to search for.\")\n@click.pass_obj\n@handle_errors\ndef file_search(\n obj: ClientContext, sandbox_id: str, path: str, pattern: str\n) -> None:\n \"\"\"Search for files in the sandbox.\"\"\"\n from opensandbox.models.filesystem import SearchEntry\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n results = sandbox.files.search(SearchEntry(path=path, pattern=pattern))\n if not results:\n if obj.output.fmt in (\"json\", \"yaml\"):\n obj.output.print_models([], columns=[])\n else:\n obj.output.info(\"No files found.\")\n return\n if obj.output.fmt in (\"json\", \"yaml\"):\n obj.output.print_models(results, columns=[\"path\", \"size\", \"mode\", \"owner\", \"modified_at\"])\n else:\n obj.output.print_models(results, columns=[\"path\", \"size\", \"owner\"], title=\"Search Results\")\n finally:\n sandbox.close()\n\n\n# ---- info (stat) ----------------------------------------------------------\n\n@file_group.command(\"info\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"paths\", nargs=-1, required=True)\n@click.pass_obj\n@handle_errors\ndef file_info(obj: ClientContext, sandbox_id: str, paths: tuple[str, ...]) -> None:\n \"\"\"Get file/directory info.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n info_map = sandbox.files.get_file_info(list(paths))\n for path, entry in info_map.items():\n obj.output.print_dict(\n {\"path\": path, **entry.model_dump(mode=\"json\")},\n title=path,\n )\n finally:\n sandbox.close()\n\n\n# ---- chmod ----------------------------------------------------------------\n\n@file_group.command(\"chmod\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"path\")\n@click.option(\"--mode\", required=True, help=\"Permission mode (e.g. 0755).\")\n@click.option(\"--owner\", default=None, help=\"File owner.\")\n@click.option(\"--group\", default=None, help=\"File group.\")\n@click.pass_obj\n@handle_errors\ndef file_chmod(\n obj: ClientContext,\n sandbox_id: str,\n path: str,\n mode: str,\n owner: str | None,\n group: str | None,\n) -> None:\n \"\"\"Set file permissions.\"\"\"\n from opensandbox.models.filesystem import SetPermissionEntry\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n sandbox.files.set_permissions(\n [SetPermissionEntry(path=path, mode=mode, owner=owner, group=group)]\n )\n obj.output.success(f\"Permissions set: {path}\")\n finally:\n sandbox.close()\n\n\n# ---- replace --------------------------------------------------------------\n\n@file_group.command(\"replace\")\n@click.argument(\"sandbox_id\")\n@click.argument(\"path\")\n@click.option(\"--old\", required=True, help=\"Text to search for.\")\n@click.option(\"--new\", required=True, help=\"Replacement text.\")\n@click.pass_obj\n@handle_errors\ndef file_replace(\n obj: ClientContext, sandbox_id: str, path: str, old: str, new: str\n) -> None:\n \"\"\"Replace content in a file.\"\"\"\n from opensandbox.models.filesystem import ContentReplaceEntry\n\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n sandbox.files.replace_contents(\n [ContentReplaceEntry(path=path, old_content=old, new_content=new)]\n )\n obj.output.success(f\"Replaced in: {path}\")\n finally:\n sandbox.close()\n" }, { "path": "cli/src/opensandbox_cli/commands/sandbox.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Sandbox lifecycle commands: create, list, get, kill, pause, resume, renew, endpoint, health, metrics.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom datetime import timedelta\n\nimport click\n\nfrom opensandbox.models.sandboxes import NetworkPolicy, SandboxFilter\n\nfrom opensandbox_cli.client import ClientContext\nfrom opensandbox_cli.utils import DURATION, KEY_VALUE, handle_errors\n\n\n@click.group(\"sandbox\", invoke_without_command=True)\n@click.pass_context\ndef sandbox_group(ctx: click.Context) -> None:\n \"\"\"๐Ÿ“ฆ Manage sandbox lifecycle.\"\"\"\n if ctx.invoked_subcommand is None:\n click.echo(ctx.get_help())\n\n\n# Alias: osb sb ...\nsandbox_group.name = \"sandbox\"\n\n\n# ---- create ---------------------------------------------------------------\n\n@sandbox_group.command(\"create\")\n@click.option(\"--image\", \"-i\", required=True, help=\"Container image (e.g. python:3.11).\")\n@click.option(\"--timeout\", \"-t\", \"timeout\", type=DURATION, default=None, help=\"Sandbox lifetime (e.g. 10m, 1h).\")\n@click.option(\"--env\", \"-e\", \"envs\", multiple=True, type=KEY_VALUE, help=\"Environment variable (KEY=VALUE). Repeatable.\")\n@click.option(\"--metadata\", \"-m\", \"metadata_kv\", multiple=True, type=KEY_VALUE, help=\"Metadata (KEY=VALUE). Repeatable.\")\n@click.option(\"--resource\", \"resources_kv\", multiple=True, type=KEY_VALUE, help=\"Resource limit (e.g. cpu=1 memory=2Gi). Repeatable.\")\n@click.option(\"--entrypoint\", default=None, help=\"Entrypoint command (JSON array or shell string).\")\n@click.option(\"--network-policy-file\", type=click.Path(exists=True), default=None, help=\"Network policy JSON file.\")\n@click.option(\"--skip-health-check\", is_flag=True, default=False, help=\"Skip waiting for sandbox readiness.\")\n@click.option(\"--ready-timeout\", type=DURATION, default=None, help=\"Max wait time for sandbox readiness (e.g. 30s).\")\n@click.pass_obj\n@handle_errors\ndef sandbox_create(\n obj: ClientContext,\n image: str,\n timeout: timedelta | None,\n envs: tuple[tuple[str, str], ...],\n metadata_kv: tuple[tuple[str, str], ...],\n resources_kv: tuple[tuple[str, str], ...],\n entrypoint: str | None,\n network_policy_file: str | None,\n skip_health_check: bool,\n ready_timeout: timedelta | None,\n) -> None:\n \"\"\"Create a new sandbox.\"\"\"\n from opensandbox.sync.sandbox import SandboxSync\n\n kwargs: dict = {\n \"connection_config\": obj.connection_config,\n \"skip_health_check\": skip_health_check,\n }\n if timeout is not None:\n kwargs[\"timeout\"] = timeout\n if ready_timeout is not None:\n kwargs[\"ready_timeout\"] = ready_timeout\n if envs:\n kwargs[\"env\"] = dict(envs)\n if metadata_kv:\n kwargs[\"metadata\"] = dict(metadata_kv)\n if resources_kv:\n kwargs[\"resource\"] = dict(resources_kv)\n if entrypoint:\n try:\n kwargs[\"entrypoint\"] = json.loads(entrypoint)\n except json.JSONDecodeError:\n kwargs[\"entrypoint\"] = [\"sh\", \"-c\", entrypoint]\n if network_policy_file:\n with open(network_policy_file) as f:\n kwargs[\"network_policy\"] = NetworkPolicy(**json.load(f))\n\n with obj.output.spinner(\"Creating sandbox...\"):\n sandbox = SandboxSync.create(image, **kwargs)\n obj.output.success_panel(\n {\"id\": sandbox.id, \"image\": image, \"status\": \"created\"},\n title=\"Sandbox Created\",\n )\n\n\n# ---- list -----------------------------------------------------------------\n\n@sandbox_group.command(\"list\")\n@click.option(\"--state\", \"-s\", \"states\", multiple=True, help=\"Filter by state (Pending, Running, Paused, ...). Repeatable.\")\n@click.option(\"--metadata\", \"-m\", \"metadata_kv\", multiple=True, type=KEY_VALUE, help=\"Metadata filter (KEY=VALUE). Repeatable.\")\n@click.option(\"--page\", type=int, default=None, help=\"Page number (0-indexed).\")\n@click.option(\"--page-size\", type=int, default=None, help=\"Items per page.\")\n@click.pass_obj\n@handle_errors\ndef sandbox_list(\n obj: ClientContext,\n states: tuple[str, ...],\n metadata_kv: tuple[tuple[str, str], ...],\n page: int | None,\n page_size: int | None,\n) -> None:\n \"\"\"List sandboxes.\"\"\"\n mgr = obj.get_manager()\n filt = SandboxFilter(\n states=list(states) if states else None,\n metadata=dict(metadata_kv) if metadata_kv else None,\n page=page,\n page_size=page_size,\n )\n with obj.output.spinner(\"Fetching sandboxes...\"):\n result = mgr.list_sandbox_infos(filt)\n if not result.sandbox_infos:\n if obj.output.fmt in (\"json\", \"yaml\"):\n obj.output.print_rows(\n [], columns=[\"id\", \"status\", \"image\", \"created_at\", \"expires_at\"],\n title=\"Sandboxes\",\n )\n else:\n obj.output.info(\"No sandboxes found.\")\n return\n\n raw_rows = [info.model_dump(mode=\"json\") for info in result.sandbox_infos]\n\n # For machine-readable formats, preserve the original structure\n if obj.output.fmt in (\"json\", \"yaml\"):\n obj.output.print_rows(\n raw_rows,\n columns=[\"id\", \"status\", \"image\", \"created_at\", \"expires_at\"],\n title=\"Sandboxes\",\n )\n return\n\n # Flatten nested status/image objects for clean table display\n rows = []\n for d in raw_rows:\n flat = dict(d)\n status_val = flat.get(\"status\")\n if isinstance(status_val, dict):\n flat[\"status\"] = status_val.get(\"state\", str(status_val))\n image_val = flat.get(\"image\")\n if isinstance(image_val, dict):\n flat[\"image\"] = image_val.get(\"image\", str(image_val))\n rows.append(flat)\n\n obj.output.print_rows(\n rows,\n columns=[\"id\", \"status\", \"image\", \"created_at\", \"expires_at\"],\n title=\"Sandboxes\",\n )\n\n\n# ---- get ------------------------------------------------------------------\n\n@sandbox_group.command(\"get\")\n@click.argument(\"sandbox_id\")\n@click.pass_obj\n@handle_errors\ndef sandbox_get(obj: ClientContext, sandbox_id: str) -> None:\n \"\"\"Get sandbox details.\"\"\"\n sandbox_id = obj.resolve_sandbox_id(sandbox_id)\n mgr = obj.get_manager()\n info = mgr.get_sandbox_info(sandbox_id)\n d = info.model_dump(mode=\"json\")\n\n # For machine-readable formats, preserve the original structure\n if obj.output.fmt in (\"json\", \"yaml\"):\n obj.output.print_dict(d, title=\"Sandbox Info\")\n return\n\n # Flatten nested objects for clean table display\n status_val = d.get(\"status\")\n if isinstance(status_val, dict):\n d[\"status\"] = status_val.get(\"state\", str(status_val))\n if status_val.get(\"reason\"):\n d[\"status_reason\"] = status_val[\"reason\"]\n if status_val.get(\"message\"):\n d[\"status_message\"] = status_val[\"message\"]\n image_val = d.get(\"image\")\n if isinstance(image_val, dict):\n d[\"image\"] = image_val.get(\"image\", str(image_val))\n obj.output.print_dict(d, title=\"Sandbox Info\")\n\n\n# ---- kill -----------------------------------------------------------------\n\n@sandbox_group.command(\"kill\")\n@click.argument(\"sandbox_ids\", nargs=-1, required=True)\n@click.pass_obj\n@handle_errors\ndef sandbox_kill(obj: ClientContext, sandbox_ids: tuple[str, ...]) -> None:\n \"\"\"Terminate one or more sandboxes.\"\"\"\n mgr = obj.get_manager()\n for sid in sandbox_ids:\n resolved = obj.resolve_sandbox_id(sid)\n with obj.output.spinner(f\"Killing sandbox {resolved}...\"):\n mgr.kill_sandbox(resolved)\n obj.output.success(f\"Sandbox terminated: {resolved}\")\n\n\n# ---- pause ----------------------------------------------------------------\n\n@sandbox_group.command(\"pause\")\n@click.argument(\"sandbox_id\")\n@click.pass_obj\n@handle_errors\ndef sandbox_pause(obj: ClientContext, sandbox_id: str) -> None:\n \"\"\"Pause a running sandbox.\"\"\"\n sandbox_id = obj.resolve_sandbox_id(sandbox_id)\n mgr = obj.get_manager()\n with obj.output.spinner(\"Pausing sandbox...\"):\n mgr.pause_sandbox(sandbox_id)\n obj.output.success(f\"Sandbox paused: {sandbox_id}\")\n\n\n# ---- resume ---------------------------------------------------------------\n\n@sandbox_group.command(\"resume\")\n@click.argument(\"sandbox_id\")\n@click.pass_obj\n@handle_errors\ndef sandbox_resume(obj: ClientContext, sandbox_id: str) -> None:\n \"\"\"Resume a paused sandbox.\"\"\"\n sandbox_id = obj.resolve_sandbox_id(sandbox_id)\n mgr = obj.get_manager()\n with obj.output.spinner(\"Resuming sandbox...\"):\n mgr.resume_sandbox(sandbox_id)\n obj.output.success(f\"Sandbox resumed: {sandbox_id}\")\n\n\n# ---- renew ----------------------------------------------------------------\n\n@sandbox_group.command(\"renew\")\n@click.argument(\"sandbox_id\")\n@click.option(\"--timeout\", \"-t\", required=True, type=DURATION, help=\"New TTL duration (e.g. 30m, 2h).\")\n@click.pass_obj\n@handle_errors\ndef sandbox_renew(obj: ClientContext, sandbox_id: str, timeout: timedelta) -> None:\n \"\"\"Renew sandbox expiration.\"\"\"\n sandbox_id = obj.resolve_sandbox_id(sandbox_id)\n mgr = obj.get_manager()\n with obj.output.spinner(\"Renewing sandbox...\"):\n resp = mgr.renew_sandbox(sandbox_id, timeout)\n obj.output.success_panel(\n {\"sandbox_id\": sandbox_id, \"expires_at\": str(resp.expires_at)},\n title=\"Sandbox Renewed\",\n )\n\n\n# ---- endpoint -------------------------------------------------------------\n\n@sandbox_group.command(\"endpoint\")\n@click.argument(\"sandbox_id\")\n@click.option(\"--port\", \"-p\", required=True, type=int, help=\"Port number.\")\n@click.pass_obj\n@handle_errors\ndef sandbox_endpoint(obj: ClientContext, sandbox_id: str, port: int) -> None:\n \"\"\"Get the public endpoint for a sandbox port.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n ep = sandbox.get_endpoint(port)\n obj.output.print_model(ep, title=\"Sandbox Endpoint\")\n finally:\n sandbox.close()\n\n\n# ---- health ---------------------------------------------------------------\n\n@sandbox_group.command(\"health\")\n@click.argument(\"sandbox_id\")\n@click.pass_obj\n@handle_errors\ndef sandbox_health(obj: ClientContext, sandbox_id: str) -> None:\n \"\"\"Check sandbox health.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n healthy = sandbox.is_healthy()\n if obj.output.fmt == \"table\":\n if healthy:\n obj.output.success(f\"Sandbox {sandbox_id} is healthy\")\n else:\n obj.output.error(f\"Sandbox {sandbox_id} is unhealthy\")\n else:\n obj.output.print_dict(\n {\"sandbox_id\": sandbox_id, \"healthy\": healthy},\n title=\"Health Check\",\n )\n finally:\n sandbox.close()\n\n\n# ---- metrics --------------------------------------------------------------\n\n@sandbox_group.command(\"metrics\")\n@click.argument(\"sandbox_id\")\n@click.pass_obj\n@handle_errors\ndef sandbox_metrics(obj: ClientContext, sandbox_id: str) -> None:\n \"\"\"Get sandbox resource metrics.\"\"\"\n sandbox = obj.connect_sandbox(sandbox_id)\n try:\n m = sandbox.get_metrics()\n obj.output.print_model(m, title=\"Sandbox Metrics\")\n finally:\n sandbox.close()\n" }, { "path": "cli/src/opensandbox_cli/config.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"CLI configuration loading and management.\n\nPriority (highest to lowest):\n 1. CLI flags\n 2. Environment variables\n 3. Config file (~/.opensandbox/config.toml)\n 4. SDK defaults\n\"\"\"\n\nfrom __future__ import annotations\n\nimport os\nimport sys\nfrom pathlib import Path\nfrom typing import Any\n\nif sys.version_info >= (3, 11):\n import tomllib\nelse:\n try:\n import tomli as tomllib # type: ignore[no-redef]\n except ModuleNotFoundError: # pragma: no cover\n tomllib = None # type: ignore[assignment]\n\n\nDEFAULT_CONFIG_DIR = Path.home() / \".opensandbox\"\nDEFAULT_CONFIG_PATH = DEFAULT_CONFIG_DIR / \"config.toml\"\n\nDEFAULT_CONFIG_TEMPLATE = \"\"\"\\\n# OpenSandbox CLI configuration\n# Priority: CLI flags > environment variables > this file > SDK defaults\n\n[connection]\n# api_key = \"your-api-key\"\n# domain = \"localhost:8080\"\n# protocol = \"http\"\n# request_timeout = 30\n\n[output]\n# format = \"table\" # table | json | yaml\n# color = true\n\n[defaults]\n# image = \"python:3.11\"\n# timeout = \"10m\"\n\"\"\"\n\n\ndef load_config_file(config_path: Path | None = None) -> dict[str, Any]:\n \"\"\"Load and parse the TOML config file.\n\n Returns an empty dict if the file doesn't exist or tomllib is unavailable.\n \"\"\"\n path = config_path or DEFAULT_CONFIG_PATH\n if not path.exists():\n return {}\n if tomllib is None:\n return {}\n with open(path, \"rb\") as f:\n return tomllib.load(f)\n\n\ndef resolve_config(\n *,\n cli_api_key: str | None = None,\n cli_domain: str | None = None,\n cli_protocol: str | None = None,\n cli_timeout: int | None = None,\n cli_output: str | None = None,\n config_path: Path | None = None,\n) -> dict[str, Any]:\n \"\"\"Merge config from all sources and return a flat dict.\n\n Keys returned:\n - api_key, domain, protocol, request_timeout (int seconds)\n - output_format (\"table\" | \"json\" | \"yaml\")\n - default_image, default_timeout (str like \"10m\")\n \"\"\"\n file_cfg = load_config_file(config_path)\n conn = file_cfg.get(\"connection\", {})\n output_cfg = file_cfg.get(\"output\", {})\n defaults = file_cfg.get(\"defaults\", {})\n\n return {\n \"api_key\": cli_api_key\n or os.getenv(\"OPEN_SANDBOX_API_KEY\")\n or conn.get(\"api_key\"),\n \"domain\": cli_domain\n or os.getenv(\"OPEN_SANDBOX_DOMAIN\")\n or conn.get(\"domain\"),\n \"protocol\": cli_protocol\n or os.getenv(\"OPEN_SANDBOX_PROTOCOL\")\n or conn.get(\"protocol\")\n or \"http\",\n \"request_timeout\": cli_timeout\n or _int_or_none(os.getenv(\"OPEN_SANDBOX_REQUEST_TIMEOUT\"))\n or conn.get(\"request_timeout\")\n or 30,\n \"output_format\": cli_output\n or os.getenv(\"OPEN_SANDBOX_OUTPUT\")\n or output_cfg.get(\"format\")\n or \"table\",\n \"color\": output_cfg.get(\"color\", True),\n \"default_image\": defaults.get(\"image\"),\n \"default_timeout\": defaults.get(\"timeout\"),\n }\n\n\ndef init_config_file(config_path: Path | None = None, *, force: bool = False) -> Path:\n \"\"\"Create a default config file. Returns the path written.\"\"\"\n path = config_path or DEFAULT_CONFIG_PATH\n if path.exists() and not force:\n raise FileExistsError(\n f\"Config file already exists at {path}. Use --force to overwrite.\"\n )\n path.parent.mkdir(parents=True, exist_ok=True)\n path.write_text(DEFAULT_CONFIG_TEMPLATE)\n return path\n\n\ndef _int_or_none(value: str | None) -> int | None:\n if value is None:\n return None\n try:\n return int(value)\n except ValueError:\n return None\n" }, { "path": "cli/src/opensandbox_cli/main.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Root Click group with global options.\"\"\"\n\nfrom __future__ import annotations\n\nfrom pathlib import Path\n\nimport click\nfrom rich.console import Console\nfrom rich.text import Text\n\nfrom opensandbox_cli import __version__\nfrom opensandbox_cli.client import ClientContext\nfrom opensandbox_cli.commands.code import code_group\nfrom opensandbox_cli.commands.command import command_group, exec_cmd\nfrom opensandbox_cli.commands.config_cmd import config_group\nfrom opensandbox_cli.commands.file import file_group\nfrom opensandbox_cli.commands.sandbox import sandbox_group\nfrom opensandbox_cli.config import resolve_config\nfrom opensandbox_cli.output import OutputFormatter\n\n# ---------------------------------------------------------------------------\n# Banner\n# ---------------------------------------------------------------------------\n\nBANNER = r\"\"\"[bold cyan]\n ____ _____ _ _\n / __ \\ / ____| | | |\n | | | |_ __ ___ _ _| (___ __ _ _ __ __| | |__ _____ __\n | | | | '_ \\ / _ \\ '_ \\___ \\ / _` | '_ \\ / _` | '_ \\ / _ \\ \\/ /\n | |__| | |_) | __/ | | |___) | (_| | | | | (_| | |_) | (_) > <\n \\____/| .__/ \\___|_| |_|____/ \\__,_|_| |_|\\__,_|_.__/ \\___/_/\\_\\\n | |\n |_|[/] [dim]v{version}[/]\n\"\"\"\n\n\nclass BannerGroup(click.Group):\n \"\"\"Custom Click group that shows a banner before help text.\"\"\"\n\n def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:\n console = Console(stderr=False)\n console.print(BANNER.format(version=__version__))\n super().format_help(ctx, formatter)\n\n\n@click.group(cls=BannerGroup, context_settings={\"help_option_names\": [\"-h\", \"--help\"]})\n@click.option(\"--api-key\", envvar=\"OPEN_SANDBOX_API_KEY\", default=None, help=\"API key for authentication.\")\n@click.option(\"--domain\", envvar=\"OPEN_SANDBOX_DOMAIN\", default=None, help=\"API server domain (e.g. localhost:8080).\")\n@click.option(\"--protocol\", type=click.Choice([\"http\", \"https\"]), default=None, help=\"Protocol (http/https).\")\n@click.option(\"--timeout\", \"request_timeout\", type=int, default=None, help=\"Request timeout in seconds.\")\n@click.option(\"-o\", \"--output\", \"output_format\", type=click.Choice([\"table\", \"json\", \"yaml\"]), default=None, help=\"Output format.\")\n@click.option(\"--config\", \"config_path\", type=click.Path(exists=False, path_type=Path), default=None, help=\"Config file path.\")\n@click.option(\"-v\", \"--verbose\", is_flag=True, default=False, help=\"Enable verbose/debug output.\")\n@click.option(\"--no-color\", is_flag=True, default=False, help=\"Disable colored output.\")\n@click.version_option(version=__version__, prog_name=\"opensandbox\")\n@click.pass_context\ndef cli(\n ctx: click.Context,\n api_key: str | None,\n domain: str | None,\n protocol: str | None,\n request_timeout: int | None,\n output_format: str | None,\n config_path: Path | None,\n verbose: bool,\n no_color: bool,\n) -> None:\n \"\"\"OpenSandbox CLI โ€” manage sandboxes from your terminal.\"\"\"\n if verbose:\n import logging\n\n logging.basicConfig(level=logging.DEBUG)\n\n resolved = resolve_config(\n cli_api_key=api_key,\n cli_domain=domain,\n cli_protocol=protocol,\n cli_timeout=request_timeout,\n cli_output=output_format,\n config_path=config_path,\n )\n\n formatter = OutputFormatter(\n resolved[\"output_format\"],\n color=not no_color and resolved.get(\"color\", True),\n )\n\n ctx.obj = ClientContext(resolved_config=resolved, output=formatter)\n ctx.call_on_close(lambda: ctx.obj.close())\n\n\n# Register sub-command groups\ncli.add_command(sandbox_group)\ncli.add_command(command_group)\ncli.add_command(exec_cmd)\ncli.add_command(file_group)\ncli.add_command(code_group)\ncli.add_command(config_group)\n" }, { "path": "cli/src/opensandbox_cli/output.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Output formatting: table (rich), JSON, YAML.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport sys\nfrom contextlib import contextmanager\nfrom typing import Any, Generator, Sequence\n\nimport click\n\ntry:\n import yaml\nexcept ImportError: # pragma: no cover\n yaml = None # type: ignore[assignment]\n\nfrom pydantic import BaseModel\nfrom rich import box\nfrom rich.console import Console\nfrom rich.panel import Panel\nfrom rich.status import Status\nfrom rich.table import Table\nfrom rich.text import Text\n\n# ---------------------------------------------------------------------------\n# Status badge styling (sandbox state โ†’ color + icon)\n# ---------------------------------------------------------------------------\n\n_STATUS_STYLES: dict[str, tuple[str, str]] = {\n # state โ†’ (rich style, icon)\n \"running\": (\"bold green\", \"โ—\"),\n \"ready\": (\"bold green\", \"โ—\"),\n \"healthy\": (\"bold green\", \"โ—\"),\n \"pending\": (\"bold yellow\", \"โ—\"),\n \"creating\": (\"bold yellow\", \"โ—\"),\n \"starting\": (\"bold yellow\", \"โ—\"),\n \"paused\": (\"bold blue\", \"โธ\"),\n \"stopped\": (\"dim\", \"โ—‹\"),\n \"terminated\": (\"dim\", \"โ—‹\"),\n \"killed\": (\"dim\", \"โ—‹\"),\n \"error\": (\"bold red\", \"โœ—\"),\n \"failed\": (\"bold red\", \"โœ—\"),\n \"unhealthy\": (\"bold red\", \"โœ—\"),\n \"created\": (\"bold cyan\", \"โœฆ\"),\n}\n\n# Columns that contain status-like values\n_STATUS_COLUMNS = {\"status\", \"state\", \"healthy\"}\n\n# Columns that should be rendered in a dimmer style (long IDs, timestamps)\n_DIM_COLUMNS = {\"created_at\", \"expires_at\", \"modified_at\", \"updated_at\"}\n\n# Columns that are primary identifiers\n_ID_COLUMNS = {\"id\", \"sandbox_id\", \"execution_id\", \"context_id\"}\n\n\ndef _style_value(col: str, value: str) -> Text:\n \"\"\"Apply contextual styling to a cell value.\"\"\"\n lower = value.lower()\n\n if col in _STATUS_COLUMNS:\n style, icon = _STATUS_STYLES.get(lower, (\"\", \"\"))\n if style:\n return Text(f\"{icon} {value}\", style=style)\n\n if col in _DIM_COLUMNS:\n return Text(value, style=\"dim\")\n\n if col in _ID_COLUMNS:\n return Text(value, style=\"bold cyan\")\n\n return Text(value)\n\n\nclass OutputFormatter:\n \"\"\"Renders data in table / json / yaml format.\"\"\"\n\n def __init__(self, fmt: str = \"table\", *, color: bool = True) -> None:\n self.fmt = fmt\n self.color = color\n self.console = Console(\n stderr=False, no_color=not color, force_terminal=None\n )\n self._err_console = Console(\n stderr=True, no_color=not color, force_terminal=None\n )\n\n # ------------------------------------------------------------------\n # Status messages with icons\n # ------------------------------------------------------------------\n\n def success(self, msg: str) -> None:\n \"\"\"Print a success message with โœ… icon.\"\"\"\n if self.color:\n self.console.print(f\" [bold green]โœ… {msg}[/]\")\n else:\n click.echo(f\"OK: {msg}\")\n\n def info(self, msg: str) -> None:\n \"\"\"Print an info message with โ„น๏ธ icon.\"\"\"\n if self.color:\n self.console.print(f\" [bold blue]โ„น๏ธ {msg}[/]\")\n else:\n click.echo(f\"INFO: {msg}\")\n\n def warning(self, msg: str) -> None:\n \"\"\"Print a warning message with โš ๏ธ icon.\"\"\"\n if self.color:\n self._err_console.print(f\" [bold yellow]โš ๏ธ {msg}[/]\")\n else:\n click.echo(f\"WARN: {msg}\", err=True)\n\n def error(self, msg: str) -> None:\n \"\"\"Print an error message with โŒ icon.\"\"\"\n if self.color:\n self._err_console.print(f\" [bold red]โŒ {msg}[/]\")\n else:\n click.echo(f\"ERROR: {msg}\", err=True)\n\n def error_panel(self, msg: str, title: str = \"Error\") -> None:\n \"\"\"Print an error with a bold header and message.\"\"\"\n if self.color:\n self._err_console.print()\n self._err_console.print(f\" [bold red]{title}[/]\")\n self._err_console.print(f\" [dim]{'โ”€' * (len(title) + 2)}[/]\")\n for line in msg.splitlines():\n self._err_console.print(f\" {line}\")\n self._err_console.print()\n else:\n click.echo(f\"ERROR [{title}]: {msg}\", err=True)\n\n # ------------------------------------------------------------------\n # Spinner for long-running operations\n # ------------------------------------------------------------------\n\n @contextmanager\n def spinner(self, msg: str) -> Generator[Status, None, None]:\n \"\"\"Context manager that shows a spinner while work is in progress.\"\"\"\n if self.color and self.fmt == \"table\":\n with self._err_console.status(f\"[bold cyan]โณ {msg}[/]\", spinner=\"dots\") as status:\n yield status\n else:\n # No spinner in non-color or non-table mode\n yield None # type: ignore[arg-type]\n\n # ------------------------------------------------------------------\n # Panel output\n # ------------------------------------------------------------------\n\n def panel(self, content: str, *, title: str | None = None, style: str = \"cyan\") -> None:\n \"\"\"Print content inside a styled panel.\"\"\"\n if self.color:\n self.console.print(Panel(\n content,\n title=title,\n title_align=\"left\",\n border_style=style,\n box=box.ROUNDED,\n padding=(0, 1),\n ))\n else:\n if title:\n click.echo(f\"--- {title} ---\")\n click.echo(content)\n\n def success_panel(self, data: dict[str, Any], *, title: str = \"Success\") -> None:\n \"\"\"Print a success result with a header and indented key-value pairs.\"\"\"\n if self.fmt != \"table\":\n if self.fmt == \"json\":\n self._print_json(data)\n elif self.fmt == \"yaml\":\n self._print_yaml(data)\n return\n\n if self.color:\n self.console.print()\n self.console.print(f\" [bold green]โœ“ {title}[/]\")\n self.console.print(f\" [dim]{'โ”€' * (len(title) + 2)}[/]\")\n for k, v in data.items():\n self.console.print(f\" [bold]{k}:[/] [cyan]{v}[/]\")\n self.console.print()\n else:\n click.echo(f\"--- {title} ---\")\n for k, v in data.items():\n click.echo(f\" {k}: {v}\")\n\n # ------------------------------------------------------------------\n # Public helpers\n # ------------------------------------------------------------------\n\n def print_model(self, model: BaseModel, title: str | None = None) -> None:\n \"\"\"Print a single Pydantic model as key-value panel or JSON/YAML.\"\"\"\n data = _model_to_dict(model)\n if self.fmt == \"json\":\n self._print_json(data)\n elif self.fmt == \"yaml\":\n self._print_yaml(data)\n else:\n self._print_kv_table(data, title=title)\n\n def print_models(\n self,\n models: Sequence[BaseModel],\n columns: list[str],\n *,\n title: str | None = None,\n ) -> None:\n \"\"\"Print a list of Pydantic models as a table or JSON/YAML.\"\"\"\n rows = [_model_to_dict(m) for m in models]\n if self.fmt == \"json\":\n self._print_json(rows)\n elif self.fmt == \"yaml\":\n self._print_yaml(rows)\n else:\n self._print_table(rows, columns, title=title)\n\n def print_rows(\n self,\n rows: list[dict[str, Any]],\n columns: list[str],\n *,\n title: str | None = None,\n ) -> None:\n \"\"\"Print pre-processed rows (list of dicts) as a table or JSON/YAML.\"\"\"\n if self.fmt == \"json\":\n self._print_json(rows)\n elif self.fmt == \"yaml\":\n self._print_yaml(rows)\n else:\n self._print_table(rows, columns, title=title)\n\n def print_dict(self, data: dict[str, Any], title: str | None = None) -> None:\n \"\"\"Print a flat dict.\"\"\"\n if self.fmt == \"json\":\n self._print_json(data)\n elif self.fmt == \"yaml\":\n self._print_yaml(data)\n else:\n self._print_kv_table(data, title=title)\n\n def print_text(self, text: str) -> None:\n \"\"\"Print raw text (ignores format).\"\"\"\n click.echo(text)\n\n # ------------------------------------------------------------------\n # Internal renderers\n # ------------------------------------------------------------------\n\n def _print_json(self, data: Any) -> None:\n if self.color:\n self.console.print_json(json.dumps(data, default=str))\n else:\n click.echo(json.dumps(data, indent=2, default=str))\n\n def _print_yaml(self, data: Any) -> None:\n if yaml is None:\n click.secho(\n \"PyYAML is not installed. Use --output json instead.\", fg=\"red\", err=True\n )\n sys.exit(1)\n click.echo(yaml.dump(data, default_flow_style=False, allow_unicode=True).rstrip())\n\n def _print_kv_table(self, data: dict[str, Any], *, title: str | None = None) -> None:\n table = Table(\n title=title,\n show_header=True,\n header_style=\"bold magenta\",\n title_style=\"bold cyan\",\n box=box.ROUNDED,\n border_style=\"bright_black\",\n padding=(0, 1),\n show_lines=True,\n )\n table.add_column(\"Key\", style=\"bold cyan\", no_wrap=True)\n table.add_column(\"Value\")\n for k, v in data.items():\n val_text = _style_value(k, str(v)) if v is not None else Text(\"-\", style=\"dim\")\n table.add_row(str(k), val_text)\n self.console.print(table)\n\n def _print_table(\n self,\n rows: list[dict[str, Any]],\n columns: list[str],\n *,\n title: str | None = None,\n ) -> None:\n table = Table(\n title=title,\n show_header=True,\n header_style=\"bold magenta\",\n title_style=\"bold cyan\",\n box=box.ROUNDED,\n border_style=\"bright_black\",\n padding=(0, 1),\n row_styles=[\"\", \"dim\"],\n )\n for col in columns:\n style = \"\"\n if col in _ID_COLUMNS:\n style = \"bold cyan\"\n elif col in _DIM_COLUMNS:\n style = \"dim\"\n table.add_column(col.upper(), style=style, no_wrap=(col in _ID_COLUMNS))\n\n for row in rows:\n cells: list[Text | str] = []\n for col in columns:\n val = str(row.get(col, \"-\"))\n if col in _STATUS_COLUMNS:\n cells.append(_style_value(col, val))\n else:\n cells.append(val)\n table.add_row(*cells)\n self.console.print(table)\n\n\n# ------------------------------------------------------------------\n# Helpers\n# ------------------------------------------------------------------\n\n\ndef _model_to_dict(model: BaseModel) -> dict[str, Any]:\n return model.model_dump(mode=\"json\")\n" }, { "path": "cli/src/opensandbox_cli/utils.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Shared CLI utilities: duration parsing, error handling, key-value parsing.\"\"\"\n\nfrom __future__ import annotations\n\nimport functools\nimport re\nimport sys\nfrom datetime import timedelta\n\nimport click\n\n\n# ---------------------------------------------------------------------------\n# Duration parsing (e.g. \"10m\", \"1h30m\", \"90s\", \"2h\")\n# ---------------------------------------------------------------------------\n\n_DURATION_RE = re.compile(\n r\"^(?:(?P\\d+)h)?(?:(?P\\d+)m)?(?:(?P\\d+)s)?$\"\n)\n\n\ndef parse_duration(value: str) -> timedelta:\n \"\"\"Parse a human-friendly duration string into a ``timedelta``.\n\n Supported formats: ``10m``, ``1h30m``, ``90s``, ``2h``, ``1h30m45s``.\n A plain integer is treated as seconds.\n \"\"\"\n value = value.strip()\n if not value:\n raise click.BadParameter(\"Duration cannot be empty\")\n\n # Plain integer โ†’ seconds\n if value.isdigit():\n return timedelta(seconds=int(value))\n\n m = _DURATION_RE.match(value)\n if not m or not m.group(0):\n raise click.BadParameter(\n f\"Invalid duration '{value}'. Use format like 10m, 1h30m, 90s.\"\n )\n\n hours = int(m.group(\"hours\") or 0)\n minutes = int(m.group(\"minutes\") or 0)\n seconds = int(m.group(\"seconds\") or 0)\n return timedelta(hours=hours, minutes=minutes, seconds=seconds)\n\n\nclass DurationType(click.ParamType):\n \"\"\"Click parameter type for duration strings.\"\"\"\n\n name = \"duration\"\n\n def convert(\n self, value: str, param: click.Parameter | None, ctx: click.Context | None\n ) -> timedelta:\n if isinstance(value, timedelta):\n return value\n try:\n return parse_duration(value)\n except click.BadParameter:\n self.fail(\n f\"Invalid duration '{value}'. Use format like 10m, 1h30m, 90s.\",\n param,\n ctx,\n )\n\n\nDURATION = DurationType()\n\n\n# ---------------------------------------------------------------------------\n# Key=Value parsing (e.g. --env FOO=bar)\n# ---------------------------------------------------------------------------\n\n\nclass KeyValueType(click.ParamType):\n \"\"\"Click parameter type that parses ``KEY=VALUE`` strings into a tuple.\"\"\"\n\n name = \"KEY=VALUE\"\n\n def convert(\n self, value: str, param: click.Parameter | None, ctx: click.Context | None\n ) -> tuple[str, str]:\n if isinstance(value, tuple):\n return value\n if \"=\" not in value:\n self.fail(f\"Expected KEY=VALUE format, got '{value}'\", param, ctx)\n key, _, val = value.partition(\"=\")\n return (key, val)\n\n\nKEY_VALUE = KeyValueType()\n\n\n# ---------------------------------------------------------------------------\n# Error handling decorator\n# ---------------------------------------------------------------------------\n\n\ndef handle_errors(fn): # type: ignore[no-untyped-def]\n \"\"\"Decorator that catches SDK / HTTP exceptions and prints a friendly message.\"\"\"\n\n @functools.wraps(fn)\n def wrapper(*args, **kwargs): # type: ignore[no-untyped-def]\n try:\n return fn(*args, **kwargs)\n except click.exceptions.Exit:\n raise\n except click.ClickException:\n raise\n except Exception as exc:\n # Import here to avoid circular imports at module level\n from opensandbox.exceptions import SandboxException\n\n # Try to get the OutputFormatter from the Click context\n ctx = click.get_current_context(silent=True)\n obj = getattr(ctx, \"obj\", None) if ctx else None\n output = getattr(obj, \"output\", None) if obj else None\n\n if output and hasattr(output, \"error_panel\"):\n if isinstance(exc, SandboxException):\n output.error_panel(str(exc), title=\"Sandbox Error\")\n else:\n output.error_panel(\n f\"{str(exc)}\\n\\n[dim]Type: {type(exc).__qualname__}[/]\",\n title=type(exc).__name__,\n )\n else:\n click.secho(f\"Error: {exc}\", fg=\"red\", err=True)\n sys.exit(1)\n\n return wrapper\n" }, { "path": "cli/tests/__init__.py", "content": "" }, { "path": "cli/tests/conftest.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Shared test fixtures.\"\"\"\n\nfrom __future__ import annotations\n\nfrom unittest.mock import MagicMock\n\nimport pytest\nfrom click.testing import CliRunner\n\nfrom opensandbox_cli.output import OutputFormatter\n\n\n@pytest.fixture()\ndef runner() -> CliRunner:\n return CliRunner()\n\n\n@pytest.fixture()\ndef mock_manager() -> MagicMock:\n return MagicMock()\n\n\n@pytest.fixture()\ndef mock_sandbox() -> MagicMock:\n return MagicMock()\n\n\n@pytest.fixture()\ndef mock_client_context(mock_manager: MagicMock, mock_sandbox: MagicMock) -> MagicMock:\n \"\"\"A mock ClientContext that avoids real SDK/HTTP calls.\"\"\"\n ctx = MagicMock()\n ctx.resolved_config = {\n \"api_key\": \"test-key\",\n \"domain\": \"localhost:8080\",\n \"protocol\": \"http\",\n \"request_timeout\": 30,\n \"output_format\": \"json\",\n \"color\": False,\n \"default_image\": None,\n \"default_timeout\": None,\n }\n ctx.output = OutputFormatter(\"json\", color=False)\n ctx.get_manager.return_value = mock_manager\n ctx.connect_sandbox.return_value = mock_sandbox\n ctx.connection_config = MagicMock()\n ctx.close = MagicMock()\n return ctx\n" }, { "path": "cli/tests/test_cli_help.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Tests that all CLI commands register correctly and --help exits cleanly.\"\"\"\n\nfrom __future__ import annotations\n\nimport pytest\nfrom click.testing import CliRunner\n\nfrom opensandbox_cli.main import cli\n\n\n@pytest.fixture()\ndef runner() -> CliRunner:\n return CliRunner()\n\n\n# ---------------------------------------------------------------------------\n# Root\n# ---------------------------------------------------------------------------\n\n\nclass TestRootCLI:\n def test_help(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"--help\"])\n assert result.exit_code == 0\n assert \"OpenSandbox CLI\" in result.output\n\n def test_version(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"--version\"])\n assert result.exit_code == 0\n assert \"opensandbox\" in result.output\n\n def test_root_lists_commands(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"--help\"])\n for cmd in (\"sandbox\", \"command\", \"exec\", \"file\", \"code\", \"config\"):\n assert cmd in result.output\n\n\n# ---------------------------------------------------------------------------\n# Sandbox sub-commands\n# ---------------------------------------------------------------------------\n\n\nclass TestSandboxHelp:\n def test_sandbox_help(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"sandbox\", \"--help\"])\n assert result.exit_code == 0\n for subcmd in (\"create\", \"list\", \"get\", \"kill\", \"pause\", \"resume\", \"renew\", \"endpoint\", \"health\", \"metrics\"):\n assert subcmd in result.output\n\n @pytest.mark.parametrize(\n \"subcmd\",\n [\"create\", \"list\", \"get\", \"kill\", \"pause\", \"resume\", \"renew\", \"endpoint\", \"health\", \"metrics\"],\n )\n def test_sandbox_subcommand_help(self, runner: CliRunner, subcmd: str) -> None:\n result = runner.invoke(cli, [\"sandbox\", subcmd, \"--help\"])\n assert result.exit_code == 0\n assert subcmd in result.output.lower() or \"usage\" in result.output.lower()\n\n\n# ---------------------------------------------------------------------------\n# Command sub-commands\n# ---------------------------------------------------------------------------\n\n\nclass TestCommandHelp:\n def test_command_help(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"command\", \"--help\"])\n assert result.exit_code == 0\n for subcmd in (\"run\", \"status\", \"logs\", \"interrupt\"):\n assert subcmd in result.output\n\n @pytest.mark.parametrize(\"subcmd\", [\"run\", \"status\", \"logs\", \"interrupt\"])\n def test_command_subcommand_help(self, runner: CliRunner, subcmd: str) -> None:\n result = runner.invoke(cli, [\"command\", subcmd, \"--help\"])\n assert result.exit_code == 0\n\n\n# ---------------------------------------------------------------------------\n# exec (top-level shortcut)\n# ---------------------------------------------------------------------------\n\n\nclass TestExecHelp:\n def test_exec_help(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"exec\", \"--help\"])\n assert result.exit_code == 0\n assert \"shortcut\" in result.output.lower() or \"command\" in result.output.lower()\n\n\n# ---------------------------------------------------------------------------\n# File sub-commands\n# ---------------------------------------------------------------------------\n\n\nclass TestFileHelp:\n def test_file_help(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"file\", \"--help\"])\n assert result.exit_code == 0\n for subcmd in (\"cat\", \"write\", \"upload\", \"download\", \"rm\", \"mv\", \"mkdir\", \"rmdir\", \"search\", \"info\", \"chmod\", \"replace\"):\n assert subcmd in result.output\n\n @pytest.mark.parametrize(\n \"subcmd\",\n [\"cat\", \"write\", \"upload\", \"download\", \"rm\", \"mv\", \"mkdir\", \"rmdir\", \"search\", \"info\", \"chmod\", \"replace\"],\n )\n def test_file_subcommand_help(self, runner: CliRunner, subcmd: str) -> None:\n result = runner.invoke(cli, [\"file\", subcmd, \"--help\"])\n assert result.exit_code == 0\n\n\n# ---------------------------------------------------------------------------\n# Code sub-commands\n# ---------------------------------------------------------------------------\n\n\nclass TestCodeHelp:\n def test_code_help(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"code\", \"--help\"])\n assert result.exit_code == 0\n for subcmd in (\"run\", \"context\", \"interrupt\"):\n assert subcmd in result.output\n\n def test_code_context_help(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"code\", \"context\", \"--help\"])\n assert result.exit_code == 0\n for subcmd in (\"create\", \"list\", \"delete\", \"delete-all\"):\n assert subcmd in result.output\n\n\n# ---------------------------------------------------------------------------\n# Config sub-commands\n# ---------------------------------------------------------------------------\n\n\nclass TestConfigHelp:\n def test_config_help(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"config\", \"--help\"])\n assert result.exit_code == 0\n for subcmd in (\"init\", \"show\", \"set\"):\n assert subcmd in result.output\n\n @pytest.mark.parametrize(\"subcmd\", [\"init\", \"show\", \"set\"])\n def test_config_subcommand_help(self, runner: CliRunner, subcmd: str) -> None:\n result = runner.invoke(cli, [\"config\", subcmd, \"--help\"])\n assert result.exit_code == 0\n" }, { "path": "cli/tests/test_commands.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Tests for CLI commands with mocked SDK calls.\n\nStrategy: patch ``opensandbox_cli.main.ClientContext`` and ``resolve_config``\nso the root ``cli`` callback creates our mock instead of a real SDK client.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom pathlib import Path\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\nfrom click.testing import CliRunner\n\nfrom opensandbox_cli.main import cli\nfrom opensandbox_cli.output import OutputFormatter\n\n\n@pytest.fixture()\ndef runner() -> CliRunner:\n return CliRunner()\n\n\ndef _build_mock_client_context(\n *,\n manager: MagicMock | None = None,\n sandbox: MagicMock | None = None,\n output_format: str = \"json\",\n) -> MagicMock:\n ctx = MagicMock()\n ctx.resolved_config = {\n \"api_key\": \"test-key\",\n \"domain\": \"localhost:8080\",\n \"protocol\": \"http\",\n \"request_timeout\": 30,\n \"output_format\": output_format,\n \"color\": False,\n \"default_image\": None,\n \"default_timeout\": None,\n }\n ctx.output = OutputFormatter(output_format, color=False)\n ctx.get_manager.return_value = manager or MagicMock()\n ctx.connect_sandbox.return_value = sandbox or MagicMock()\n ctx.resolve_sandbox_id.side_effect = lambda prefix: prefix # passthrough\n ctx.connection_config = MagicMock()\n ctx.close = MagicMock()\n return ctx\n\n\ndef _invoke(\n runner: CliRunner,\n args: list[str],\n *,\n manager: MagicMock | None = None,\n sandbox: MagicMock | None = None,\n output_format: str = \"json\",\n) -> object:\n \"\"\"Invoke CLI with mocked ClientContext.\"\"\"\n mock_ctx = _build_mock_client_context(\n manager=manager, sandbox=sandbox, output_format=output_format\n )\n\n with patch(\"opensandbox_cli.main.resolve_config\") as mock_resolve, \\\n patch(\"opensandbox_cli.main.ClientContext\", return_value=mock_ctx), \\\n patch(\"opensandbox_cli.main.OutputFormatter\", side_effect=lambda fmt, **kw: OutputFormatter(fmt, **kw)):\n mock_resolve.return_value = mock_ctx.resolved_config\n result = runner.invoke(cli, args, catch_exceptions=False)\n return result\n\n\n# ---------------------------------------------------------------------------\n# Config commands (no SDK mocking needed)\n# ---------------------------------------------------------------------------\n\n\nclass TestConfigInit:\n def test_init_creates_file(self, runner: CliRunner, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"config.toml\"\n result = runner.invoke(cli, [\"config\", \"init\", \"--path\", str(cfg_path)])\n assert result.exit_code == 0\n assert \"Config file created\" in result.output\n\n def test_init_refuses_overwrite(self, runner: CliRunner, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"config.toml\"\n cfg_path.write_text(\"existing\")\n result = runner.invoke(cli, [\"config\", \"init\", \"--path\", str(cfg_path)])\n assert \"already exists\" in result.output\n\n def test_init_force_overwrites(self, runner: CliRunner, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"config.toml\"\n cfg_path.write_text(\"old\")\n result = runner.invoke(cli, [\"config\", \"init\", \"--path\", str(cfg_path), \"--force\"])\n assert result.exit_code == 0\n assert \"Config file created\" in result.output\n\n\nclass TestConfigShow:\n def test_show_json_output(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"-o\", \"json\", \"config\", \"show\"])\n assert result.exit_code == 0\n data = json.loads(result.output)\n assert \"api_key\" in data\n\n def test_show_table_output(self, runner: CliRunner) -> None:\n result = runner.invoke(cli, [\"config\", \"show\"])\n assert result.exit_code == 0\n assert \"api_key\" in result.output\n\n\nclass TestConfigSet:\n def test_set_updates_existing_field(self, runner: CliRunner, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"config.toml\"\n runner.invoke(cli, [\"config\", \"init\", \"--path\", str(cfg_path)])\n result = runner.invoke(cli, [\"config\", \"set\", \"connection.domain\", \"new.host\", \"--path\", str(cfg_path)])\n assert result.exit_code == 0\n assert \"Set connection.domain = new.host\" in result.output\n\n def test_set_rejects_flat_key(self, runner: CliRunner, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"config.toml\"\n cfg_path.write_text(\"[connection]\\n\")\n result = runner.invoke(cli, [\"config\", \"set\", \"flat_key\", \"value\", \"--path\", str(cfg_path)])\n assert \"section.field\" in result.output\n\n\n# ---------------------------------------------------------------------------\n# Sandbox commands\n# ---------------------------------------------------------------------------\n\n\nclass TestSandboxList:\n def test_list_invokes_manager(self, runner: CliRunner) -> None:\n mock_mgr = MagicMock()\n mock_result = MagicMock()\n mock_result.sandbox_infos = []\n mock_mgr.list_sandbox_infos.return_value = mock_result\n\n result = _invoke(runner, [\"-o\", \"json\", \"sandbox\", \"list\"], manager=mock_mgr)\n assert result.exit_code == 0\n mock_mgr.list_sandbox_infos.assert_called_once()\n\n\nclass TestSandboxKill:\n def test_kill_multiple(self, runner: CliRunner) -> None:\n mock_mgr = MagicMock()\n result = _invoke(runner, [\"sandbox\", \"kill\", \"id1\", \"id2\"], manager=mock_mgr)\n assert result.exit_code == 0\n assert mock_mgr.kill_sandbox.call_count == 2\n assert \"Sandbox terminated: id1\" in result.output\n assert \"Sandbox terminated: id2\" in result.output\n\n\nclass TestSandboxPause:\n def test_pause_calls_manager(self, runner: CliRunner) -> None:\n mock_mgr = MagicMock()\n result = _invoke(runner, [\"sandbox\", \"pause\", \"sb-123\"], manager=mock_mgr)\n assert result.exit_code == 0\n mock_mgr.pause_sandbox.assert_called_once_with(\"sb-123\")\n assert \"Sandbox paused: sb-123\" in result.output\n\n\nclass TestSandboxResume:\n def test_resume_calls_manager(self, runner: CliRunner) -> None:\n mock_mgr = MagicMock()\n result = _invoke(runner, [\"sandbox\", \"resume\", \"sb-123\"], manager=mock_mgr)\n assert result.exit_code == 0\n mock_mgr.resume_sandbox.assert_called_once_with(\"sb-123\")\n assert \"Sandbox resumed: sb-123\" in result.output\n\n\n# ---------------------------------------------------------------------------\n# File commands\n# ---------------------------------------------------------------------------\n\n\nclass TestFileCat:\n def test_cat_outputs_content(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n mock_sb.files.read_file.return_value = \"hello world\"\n result = _invoke(runner, [\"file\", \"cat\", \"sb-1\", \"/etc/hostname\"], sandbox=mock_sb)\n assert result.exit_code == 0\n assert \"hello world\" in result.output\n mock_sb.files.read_file.assert_called_once_with(\"/etc/hostname\", encoding=\"utf-8\")\n\n\nclass TestFileWrite:\n def test_write_with_content_flag(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n result = _invoke(\n runner,\n [\"file\", \"write\", \"sb-1\", \"/tmp/test.txt\", \"-c\", \"content here\"],\n sandbox=mock_sb,\n )\n assert result.exit_code == 0\n assert \"Written\" in result.output\n mock_sb.files.write_file.assert_called_once()\n\n\nclass TestFileRm:\n def test_rm_deletes_files(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n result = _invoke(\n runner, [\"file\", \"rm\", \"sb-1\", \"/tmp/a\", \"/tmp/b\"], sandbox=mock_sb\n )\n assert result.exit_code == 0\n mock_sb.files.delete_files.assert_called_once_with([\"/tmp/a\", \"/tmp/b\"])\n\n\nclass TestFileMv:\n def test_mv_moves_file(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n result = _invoke(\n runner, [\"file\", \"mv\", \"sb-1\", \"/tmp/old\", \"/tmp/new\"], sandbox=mock_sb\n )\n assert result.exit_code == 0\n assert \"Moved: /tmp/old\" in result.output and \"/tmp/new\" in result.output\n\n\nclass TestFileMkdir:\n def test_mkdir_creates_dirs(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n result = _invoke(\n runner, [\"file\", \"mkdir\", \"sb-1\", \"/tmp/dir1\", \"/tmp/dir2\"], sandbox=mock_sb\n )\n assert result.exit_code == 0\n assert \"Created: /tmp/dir1\" in result.output\n assert \"Created: /tmp/dir2\" in result.output\n\n\nclass TestFileRmdir:\n def test_rmdir_removes_dirs(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n result = _invoke(\n runner, [\"file\", \"rmdir\", \"sb-1\", \"/workspace/old\"], sandbox=mock_sb\n )\n assert result.exit_code == 0\n assert \"Removed: /workspace/old\" in result.output\n\n\n# ---------------------------------------------------------------------------\n# Command execution\n# ---------------------------------------------------------------------------\n\n\nclass TestCommandRun:\n def test_background_run(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n mock_execution = MagicMock()\n mock_execution.id = \"exec-123\"\n mock_sb.commands.run.return_value = mock_execution\n\n result = _invoke(\n runner,\n [\"-o\", \"json\", \"command\", \"run\", \"sb-1\", \"-d\", \"echo\", \"hello\"],\n sandbox=mock_sb,\n )\n assert result.exit_code == 0\n data = json.loads(result.output)\n assert data[\"execution_id\"] == \"exec-123\"\n assert data[\"mode\"] == \"background\"\n\n\nclass TestExecShortcut:\n def test_exec_passes_to_run(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n mock_execution = MagicMock()\n mock_execution.id = \"exec-456\"\n mock_sb.commands.run.return_value = mock_execution\n\n result = _invoke(\n runner,\n [\"-o\", \"json\", \"exec\", \"sb-1\", \"-d\", \"--\", \"ls\", \"-la\"],\n sandbox=mock_sb,\n )\n assert result.exit_code == 0\n mock_sb.commands.run.assert_called_once()\n\n\nclass TestCommandInterrupt:\n def test_interrupt_calls_sdk(self, runner: CliRunner) -> None:\n mock_sb = MagicMock()\n result = _invoke(\n runner, [\"command\", \"interrupt\", \"sb-1\", \"exec-789\"], sandbox=mock_sb\n )\n assert result.exit_code == 0\n mock_sb.commands.interrupt.assert_called_once_with(\"exec-789\")\n assert \"Interrupted: exec-789\" in result.output\n" }, { "path": "cli/tests/test_config.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Tests for opensandbox_cli.config โ€” config loading and priority merging.\"\"\"\n\nfrom __future__ import annotations\n\nimport os\nfrom pathlib import Path\n\nimport pytest\n\nfrom opensandbox_cli.config import (\n DEFAULT_CONFIG_TEMPLATE,\n init_config_file,\n load_config_file,\n resolve_config,\n)\n\n\n# ---------------------------------------------------------------------------\n# load_config_file\n# ---------------------------------------------------------------------------\n\n\nclass TestLoadConfigFile:\n def test_returns_empty_when_file_missing(self, tmp_path: Path) -> None:\n result = load_config_file(tmp_path / \"nonexistent.toml\")\n assert result == {}\n\n def test_parses_toml_file(self, tmp_path: Path) -> None:\n cfg = tmp_path / \"config.toml\"\n cfg.write_text(\n '[connection]\\napi_key = \"abc\"\\ndomain = \"example.com\"\\n'\n )\n result = load_config_file(cfg)\n assert result[\"connection\"][\"api_key\"] == \"abc\"\n assert result[\"connection\"][\"domain\"] == \"example.com\"\n\n def test_parses_all_sections(self, tmp_path: Path) -> None:\n cfg = tmp_path / \"config.toml\"\n cfg.write_text(\n '[connection]\\napi_key = \"k\"\\n\\n'\n '[output]\\nformat = \"json\"\\ncolor = false\\n\\n'\n '[defaults]\\nimage = \"alpine\"\\ntimeout = \"5m\"\\n'\n )\n result = load_config_file(cfg)\n assert result[\"output\"][\"format\"] == \"json\"\n assert result[\"output\"][\"color\"] is False\n assert result[\"defaults\"][\"image\"] == \"alpine\"\n assert result[\"defaults\"][\"timeout\"] == \"5m\"\n\n\n# ---------------------------------------------------------------------------\n# resolve_config โ€” priority: CLI > env > file > defaults\n# ---------------------------------------------------------------------------\n\n\nclass TestResolveConfig:\n def test_defaults_when_nothing_configured(self, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"empty.toml\"\n cfg_path.write_text(\"\")\n result = resolve_config(config_path=cfg_path)\n assert result[\"api_key\"] is None\n assert result[\"domain\"] is None\n assert result[\"protocol\"] == \"http\"\n assert result[\"request_timeout\"] == 30\n assert result[\"output_format\"] == \"table\"\n assert result[\"color\"] is True\n\n def test_file_values_override_defaults(self, tmp_path: Path) -> None:\n cfg = tmp_path / \"config.toml\"\n cfg.write_text(\n '[connection]\\napi_key = \"file-key\"\\ndomain = \"file.host\"\\n'\n 'protocol = \"https\"\\nrequest_timeout = 60\\n\\n'\n '[output]\\nformat = \"json\"\\ncolor = false\\n\\n'\n '[defaults]\\nimage = \"node:20\"\\ntimeout = \"15m\"\\n'\n )\n result = resolve_config(config_path=cfg)\n assert result[\"api_key\"] == \"file-key\"\n assert result[\"domain\"] == \"file.host\"\n assert result[\"protocol\"] == \"https\"\n assert result[\"request_timeout\"] == 60\n assert result[\"output_format\"] == \"json\"\n assert result[\"color\"] is False\n assert result[\"default_image\"] == \"node:20\"\n assert result[\"default_timeout\"] == \"15m\"\n\n def test_env_overrides_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:\n cfg = tmp_path / \"config.toml\"\n cfg.write_text('[connection]\\napi_key = \"file-key\"\\ndomain = \"file.host\"\\n')\n\n monkeypatch.setenv(\"OPEN_SANDBOX_API_KEY\", \"env-key\")\n monkeypatch.setenv(\"OPEN_SANDBOX_DOMAIN\", \"env.host\")\n monkeypatch.setenv(\"OPEN_SANDBOX_PROTOCOL\", \"https\")\n monkeypatch.setenv(\"OPEN_SANDBOX_REQUEST_TIMEOUT\", \"120\")\n monkeypatch.setenv(\"OPEN_SANDBOX_OUTPUT\", \"yaml\")\n\n result = resolve_config(config_path=cfg)\n assert result[\"api_key\"] == \"env-key\"\n assert result[\"domain\"] == \"env.host\"\n assert result[\"protocol\"] == \"https\"\n assert result[\"request_timeout\"] == 120\n assert result[\"output_format\"] == \"yaml\"\n\n def test_cli_overrides_everything(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:\n cfg = tmp_path / \"config.toml\"\n cfg.write_text('[connection]\\napi_key = \"file-key\"\\n')\n monkeypatch.setenv(\"OPEN_SANDBOX_API_KEY\", \"env-key\")\n\n result = resolve_config(\n cli_api_key=\"cli-key\",\n cli_domain=\"cli.host\",\n cli_protocol=\"https\",\n cli_timeout=999,\n cli_output=\"yaml\",\n config_path=cfg,\n )\n assert result[\"api_key\"] == \"cli-key\"\n assert result[\"domain\"] == \"cli.host\"\n assert result[\"protocol\"] == \"https\"\n assert result[\"request_timeout\"] == 999\n assert result[\"output_format\"] == \"yaml\"\n\n def test_invalid_timeout_env_falls_through(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:\n cfg = tmp_path / \"empty.toml\"\n cfg.write_text(\"\")\n monkeypatch.setenv(\"OPEN_SANDBOX_REQUEST_TIMEOUT\", \"not-a-number\")\n result = resolve_config(config_path=cfg)\n # Falls through to default 30\n assert result[\"request_timeout\"] == 30\n\n\n# ---------------------------------------------------------------------------\n# init_config_file\n# ---------------------------------------------------------------------------\n\n\nclass TestInitConfigFile:\n def test_creates_default_config(self, tmp_path: Path) -> None:\n cfg_path = tmp_path / \".opensandbox\" / \"config.toml\"\n result = init_config_file(cfg_path)\n assert result == cfg_path\n assert cfg_path.exists()\n content = cfg_path.read_text()\n assert \"[connection]\" in content\n assert \"[output]\" in content\n assert \"[defaults]\" in content\n\n def test_refuses_overwrite_without_force(self, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"config.toml\"\n cfg_path.write_text(\"existing\")\n with pytest.raises(FileExistsError, match=\"already exists\"):\n init_config_file(cfg_path)\n\n def test_force_overwrites(self, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"config.toml\"\n cfg_path.write_text(\"old content\")\n init_config_file(cfg_path, force=True)\n assert cfg_path.read_text() == DEFAULT_CONFIG_TEMPLATE\n\n def test_creates_parent_directories(self, tmp_path: Path) -> None:\n cfg_path = tmp_path / \"a\" / \"b\" / \"c\" / \"config.toml\"\n init_config_file(cfg_path)\n assert cfg_path.exists()\n" }, { "path": "cli/tests/test_output.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Tests for opensandbox_cli.output โ€” table, JSON, YAML rendering.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\n\nimport pytest\nfrom pydantic import BaseModel\n\nfrom opensandbox_cli.output import OutputFormatter\n\n\n# ---------------------------------------------------------------------------\n# Test models\n# ---------------------------------------------------------------------------\n\n\nclass FakeItem(BaseModel):\n id: str\n name: str\n score: int\n\n\n# ---------------------------------------------------------------------------\n# JSON output\n# ---------------------------------------------------------------------------\n\n\nclass TestJsonOutput:\n def test_print_dict(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"json\", color=False)\n fmt.print_dict({\"key\": \"value\", \"num\": 42})\n captured = capsys.readouterr()\n data = json.loads(captured.out)\n assert data == {\"key\": \"value\", \"num\": 42}\n\n def test_print_model(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"json\", color=False)\n item = FakeItem(id=\"abc\", name=\"test\", score=100)\n fmt.print_model(item)\n captured = capsys.readouterr()\n data = json.loads(captured.out)\n assert data[\"id\"] == \"abc\"\n assert data[\"name\"] == \"test\"\n assert data[\"score\"] == 100\n\n def test_print_models(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"json\", color=False)\n items = [\n FakeItem(id=\"1\", name=\"a\", score=10),\n FakeItem(id=\"2\", name=\"b\", score=20),\n ]\n fmt.print_models(items, columns=[\"id\", \"name\", \"score\"])\n captured = capsys.readouterr()\n data = json.loads(captured.out)\n assert len(data) == 2\n assert data[0][\"id\"] == \"1\"\n assert data[1][\"name\"] == \"b\"\n\n\n# ---------------------------------------------------------------------------\n# YAML output\n# ---------------------------------------------------------------------------\n\n\nclass TestYamlOutput:\n def test_print_dict(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"yaml\", color=False)\n fmt.print_dict({\"key\": \"value\"})\n captured = capsys.readouterr()\n assert \"key: value\" in captured.out\n\n def test_print_model(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"yaml\", color=False)\n item = FakeItem(id=\"x\", name=\"y\", score=5)\n fmt.print_model(item)\n captured = capsys.readouterr()\n assert \"id: x\" in captured.out\n assert \"name: y\" in captured.out\n assert \"score: 5\" in captured.out\n\n\n# ---------------------------------------------------------------------------\n# Table output\n# ---------------------------------------------------------------------------\n\n\nclass TestTableOutput:\n def test_print_dict_contains_values(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"table\", color=False)\n fmt.print_dict({\"host\": \"example.com\", \"port\": 8080}, title=\"Config\")\n captured = capsys.readouterr()\n assert \"example.com\" in captured.out\n assert \"8080\" in captured.out\n assert \"Config\" in captured.out\n\n def test_print_dict_none_renders_dash(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"table\", color=False)\n fmt.print_dict({\"key\": None})\n captured = capsys.readouterr()\n assert \"-\" in captured.out\n\n def test_print_models_shows_headers(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"table\", color=False)\n items = [FakeItem(id=\"1\", name=\"a\", score=10)]\n fmt.print_models(items, columns=[\"id\", \"name\", \"score\"], title=\"Items\")\n captured = capsys.readouterr()\n assert \"ID\" in captured.out\n assert \"NAME\" in captured.out\n assert \"SCORE\" in captured.out\n\n def test_print_text_ignores_format(self, capsys: pytest.CaptureFixture[str]) -> None:\n fmt = OutputFormatter(\"json\", color=False)\n fmt.print_text(\"hello world\")\n captured = capsys.readouterr()\n assert captured.out.strip() == \"hello world\"\n" }, { "path": "cli/tests/test_resolve_id.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Tests for Docker-style sandbox ID prefix matching.\"\"\"\n\nfrom __future__ import annotations\n\nfrom unittest.mock import MagicMock\n\nimport click\nimport pytest\n\nfrom opensandbox_cli.client import ClientContext\nfrom opensandbox_cli.output import OutputFormatter\n\n\ndef _make_sandbox_info(sandbox_id: str) -> MagicMock:\n \"\"\"Create a mock SandboxInfo with given ID.\"\"\"\n info = MagicMock()\n info.id = sandbox_id\n return info\n\n\ndef _make_paged_result(\n sandbox_ids: list[str], *, has_next_page: bool = False\n) -> MagicMock:\n \"\"\"Create a mock PagedSandboxInfos with pagination metadata.\"\"\"\n result = MagicMock()\n result.sandbox_infos = [_make_sandbox_info(sid) for sid in sandbox_ids]\n result.pagination = MagicMock()\n result.pagination.has_next_page = has_next_page\n return result\n\n\ndef _make_client_context(\n sandbox_ids: list[str],\n *,\n pages: list[list[str]] | None = None,\n) -> ClientContext:\n \"\"\"Create a ClientContext with a mocked manager listing the given IDs.\n\n If *pages* is provided, each element is a separate page of sandbox IDs\n (useful for testing pagination). Otherwise all IDs are in a single page.\n \"\"\"\n ctx = ClientContext(\n resolved_config={\n \"api_key\": \"test-key\",\n \"domain\": \"localhost:8080\",\n \"protocol\": \"http\",\n \"request_timeout\": 30,\n \"output_format\": \"json\",\n \"color\": False,\n \"default_image\": None,\n \"default_timeout\": None,\n },\n output=OutputFormatter(\"json\", color=False),\n )\n # Mock the manager\n mock_mgr = MagicMock()\n if pages is not None:\n side_effects = []\n for i, page_ids in enumerate(pages):\n has_next = i < len(pages) - 1\n side_effects.append(_make_paged_result(page_ids, has_next_page=has_next))\n mock_mgr.list_sandbox_infos.side_effect = side_effects\n else:\n mock_mgr.list_sandbox_infos.return_value = _make_paged_result(sandbox_ids)\n ctx._manager = mock_mgr\n return ctx\n\n\nclass TestResolveSandboxId:\n \"\"\"Test Docker-style prefix matching for sandbox IDs.\"\"\"\n\n def test_full_uuid_skips_listing(self) -> None:\n \"\"\"A full UUID is returned directly without calling list.\"\"\"\n ctx = _make_client_context([])\n full_id = \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n assert ctx.resolve_sandbox_id(full_id) == full_id\n # Manager should NOT have been called\n ctx._manager.list_sandbox_infos.assert_not_called()\n\n def test_unique_prefix_resolves(self) -> None:\n \"\"\"A unique prefix returns the full matching ID.\"\"\"\n ctx = _make_client_context([\n \"abc123-def456-7890-abcd-000000000001\",\n \"xyz789-def456-7890-abcd-000000000002\",\n ])\n result = ctx.resolve_sandbox_id(\"abc\")\n assert result == \"abc123-def456-7890-abcd-000000000001\"\n\n def test_exact_match_among_multiple(self) -> None:\n \"\"\"A prefix that uniquely matches one sandbox works.\"\"\"\n ctx = _make_client_context([\n \"sandbox-alpha-001\",\n \"sandbox-beta-002\",\n \"sandbox-gamma-003\",\n ])\n result = ctx.resolve_sandbox_id(\"sandbox-a\")\n assert result == \"sandbox-alpha-001\"\n\n def test_ambiguous_prefix_raises(self) -> None:\n \"\"\"Multiple matches raises ClickException with helpful message.\"\"\"\n ctx = _make_client_context([\n \"abc-111\",\n \"abc-222\",\n \"abc-333\",\n ])\n with pytest.raises(click.ClickException, match=\"Ambiguous ID prefix\"):\n ctx.resolve_sandbox_id(\"abc\")\n\n def test_ambiguous_error_shows_ids(self) -> None:\n \"\"\"The ambiguous error lists the conflicting IDs.\"\"\"\n ctx = _make_client_context([\"abc-111\", \"abc-222\"])\n with pytest.raises(click.ClickException) as exc_info:\n ctx.resolve_sandbox_id(\"abc\")\n assert \"abc-111\" in str(exc_info.value)\n assert \"abc-222\" in str(exc_info.value)\n\n def test_no_match_raises(self) -> None:\n \"\"\"No matches raises ClickException.\"\"\"\n ctx = _make_client_context([\"xyz-001\", \"xyz-002\"])\n with pytest.raises(click.ClickException, match=\"No sandbox found\"):\n ctx.resolve_sandbox_id(\"abc\")\n\n def test_empty_sandbox_list_raises(self) -> None:\n \"\"\"Empty sandbox list raises ClickException.\"\"\"\n ctx = _make_client_context([])\n with pytest.raises(click.ClickException, match=\"No sandbox found\"):\n ctx.resolve_sandbox_id(\"abc\")\n\n def test_single_char_prefix(self) -> None:\n \"\"\"Even a single character can match if unique.\"\"\"\n ctx = _make_client_context([\n \"a-sandbox-001\",\n \"b-sandbox-002\",\n ])\n result = ctx.resolve_sandbox_id(\"a\")\n assert result == \"a-sandbox-001\"\n\n def test_full_id_matches_exactly(self) -> None:\n \"\"\"A non-UUID full ID still matches via prefix logic.\"\"\"\n ctx = _make_client_context([\"my-sandbox-123\"])\n result = ctx.resolve_sandbox_id(\"my-sandbox-123\")\n assert result == \"my-sandbox-123\"\n\n def test_more_than_five_ambiguous_shows_ellipsis(self) -> None:\n \"\"\"When >5 matches, the error shows '...'.\"\"\"\n ids = [f\"sb-{i:03d}\" for i in range(10)]\n ctx = _make_client_context(ids)\n with pytest.raises(click.ClickException) as exc_info:\n ctx.resolve_sandbox_id(\"sb-\")\n assert \"...\" in str(exc_info.value)\n assert \"10 sandboxes\" in str(exc_info.value)\n\n # -- Pagination tests --\n\n def test_match_on_second_page(self) -> None:\n \"\"\"A prefix that only appears on page 2 is still found.\"\"\"\n ctx = _make_client_context(\n [],\n pages=[\n [\"xyz-001\", \"xyz-002\"],\n [\"abc-999\"],\n ],\n )\n result = ctx.resolve_sandbox_id(\"abc\")\n assert result == \"abc-999\"\n\n def test_collision_across_pages(self) -> None:\n \"\"\"Matches on different pages are detected as ambiguous.\"\"\"\n ctx = _make_client_context(\n [],\n pages=[\n [\"abc-001\"],\n [\"abc-002\"],\n ],\n )\n with pytest.raises(click.ClickException, match=\"Ambiguous ID prefix\"):\n ctx.resolve_sandbox_id(\"abc\")\n\n def test_no_match_across_all_pages(self) -> None:\n \"\"\"No match after exhausting all pages raises ClickException.\"\"\"\n ctx = _make_client_context(\n [],\n pages=[\n [\"xyz-001\"],\n [\"xyz-002\"],\n ],\n )\n with pytest.raises(click.ClickException, match=\"No sandbox found\"):\n ctx.resolve_sandbox_id(\"abc\")\n" }, { "path": "cli/tests/test_utils.py", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"Tests for opensandbox_cli.utils โ€” duration parsing, key-value type, error handling.\"\"\"\n\nfrom __future__ import annotations\n\nfrom datetime import timedelta\n\nimport click\nimport pytest\n\nfrom opensandbox_cli.utils import DURATION, KEY_VALUE, parse_duration\n\n\n# ---------------------------------------------------------------------------\n# parse_duration\n# ---------------------------------------------------------------------------\n\n\nclass TestParseDuration:\n @pytest.mark.parametrize(\n \"input_str, expected\",\n [\n (\"10\", timedelta(seconds=10)),\n (\"0\", timedelta(seconds=0)),\n (\"10s\", timedelta(seconds=10)),\n (\"5m\", timedelta(minutes=5)),\n (\"2h\", timedelta(hours=2)),\n (\"1h30m\", timedelta(hours=1, minutes=30)),\n (\"1h30m45s\", timedelta(hours=1, minutes=30, seconds=45)),\n (\"90s\", timedelta(seconds=90)),\n ],\n )\n def test_valid_durations(self, input_str: str, expected: timedelta) -> None:\n assert parse_duration(input_str) == expected\n\n @pytest.mark.parametrize(\n \"input_str\",\n [\n \"\",\n \"abc\",\n \"10x\",\n \"m10\",\n \"-5m\",\n ],\n )\n def test_invalid_durations(self, input_str: str) -> None:\n with pytest.raises(click.BadParameter):\n parse_duration(input_str)\n\n def test_strips_whitespace(self) -> None:\n assert parse_duration(\" 10m \") == timedelta(minutes=10)\n\n\n# ---------------------------------------------------------------------------\n# DurationType (Click param type)\n# ---------------------------------------------------------------------------\n\n\nclass TestDurationType:\n def test_converts_string(self) -> None:\n result = DURATION.convert(\"5m\", None, None)\n assert result == timedelta(minutes=5)\n\n def test_passes_through_timedelta(self) -> None:\n td = timedelta(hours=1)\n result = DURATION.convert(td, None, None) # type: ignore[arg-type]\n assert result is td\n\n def test_invalid_raises_bad_parameter(self) -> None:\n with pytest.raises(click.exceptions.BadParameter):\n DURATION.convert(\"invalid\", None, None)\n\n\n# ---------------------------------------------------------------------------\n# KeyValueType (Click param type)\n# ---------------------------------------------------------------------------\n\n\nclass TestKeyValueType:\n def test_parses_simple_kv(self) -> None:\n assert KEY_VALUE.convert(\"FOO=bar\", None, None) == (\"FOO\", \"bar\")\n\n def test_value_can_contain_equals(self) -> None:\n assert KEY_VALUE.convert(\"key=a=b=c\", None, None) == (\"key\", \"a=b=c\")\n\n def test_empty_value(self) -> None:\n assert KEY_VALUE.convert(\"key=\", None, None) == (\"key\", \"\")\n\n def test_missing_equals_fails(self) -> None:\n with pytest.raises(click.exceptions.BadParameter):\n KEY_VALUE.convert(\"no-equals\", None, None)\n\n def test_passes_through_tuple(self) -> None:\n t = (\"key\", \"val\")\n result = KEY_VALUE.convert(t, None, None) # type: ignore[arg-type]\n assert result is t\n" }, { "path": "components/egress/Dockerfile", "content": "# Copyright 2026 Alibaba Group Holding Ltd.\n# \n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n# \n# http://www.apache.org/licenses/LICENSE-2.0\n# \n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nFROM golang:1.24-bookworm AS builder\n\nWORKDIR /workspace\n\nARG VERSION=dev\nARG GIT_COMMIT=unknown\nARG BUILD_TIME=unknown\n\n# Copy only go mod/sum first for better caching\nCOPY components/egress/go.mod components/egress/go.sum ./components/egress/\n# Bring internal module so replace ../internal works during download/build\nCOPY components/internal ./components/internal\n\nWORKDIR /workspace/components/egress\n\n# Static-ish build (no cgo) to simplify runtime deps\nENV CGO_ENABLED=0\nRUN go mod download\n\n# Copy the rest of the egress sources\nCOPY components/egress ./\nRUN CGO_ENABLED=0 go build \\\n -ldflags \"-X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \\\n -X 'github.com/alibaba/opensandbox/internal/version.BuildTime=${BUILD_TIME}' \\\n -X 'github.com/alibaba/opensandbox/internal/version.GitCommit=${GIT_COMMIT}'\" \\\n -o /out/egress .\n\nFROM debian:bookworm-slim\n\n# iptables is needed for DNS REDIRECT; ca-certificates for TLS to upstream resolvers\nRUN apt-get update \\\n && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \\\n iptables \\\n iproute2 \\\n nftables \\\n ca-certificates \\\n sudo \\\n curl \\\n wget \\\n net-tools \\\n dnsutils \\\n netcat-openbsd \\\n iputils-ping \\\n traceroute \\\n telnet \\\n tcpdump \\\n nmap \\\n htop \\\n procps \\\n strace \\\n lsof \\\n && rm -rf /var/lib/apt/lists/*\n\nCOPY --from=builder /out/egress /egress\n\n# Default entrypoint; expects OPENSANDBOX_NETWORK_POLICY env at runtime.\nENTRYPOINT [\"/egress\"]" }, { "path": "components/egress/README.md", "content": "# OpenSandbox Egress Sidecar\n\nThe **Egress Sidecar** is a core component of OpenSandbox that provides **FQDN-based egress control**. It runs alongside the sandbox application container (sharing the same network namespace) and enforces declared network policies.\n\n## Features\n\n- **FQDN-based Allowlist**: Control outbound traffic by domain name (e.g., `api.github.com`).\n- **Wildcard Support**: Allow subdomains using wildcards (e.g., `*.pypi.org`).\n- **Transparent Interception**: Uses transparent DNS proxying; no application configuration required.\n- **Dynamic DNS (dns+nft mode)**: When a domain is allowed and the proxy resolves it, the resolved A/AAAA IPs are added to nftables with TTL so that default-deny + domain-allow is enforced at the network layer.\n- **Privilege Isolation**: Requires `CAP_NET_ADMIN` only for the sidecar; the application container runs unprivileged.\n- **Graceful Degradation**: If `CAP_NET_ADMIN` is missing, it warns and disables enforcement instead of crashing.\n\n## Architecture\n\nThe egress control is implemented as a **Sidecar** that shares the network namespace with the sandbox application.\n\n1. **DNS Proxy (Layer 1)**:\n - Runs on `127.0.0.1:15353`.\n - `iptables` rules redirect all port 53 (DNS) traffic to this proxy.\n - Filters queries based on the allowlist.\n - Returns `NXDOMAIN` for denied domains.\n\n2. **Network Filter (Layer 2)** (when `OPENSANDBOX_EGRESS_MODE=dns+nft`):\n - Uses `nftables` to enforce IP-level allow/deny. Resolved IPs for allowed domains are added to dynamic allow sets with TTL (dynamic DNS).\n - At startup, the sidecar whitelists **127.0.0.1** (redirect target for the proxy) and **nameserver IPs** from `/etc/resolv.conf` so DNS resolution and proxy upstream work (including private DNS). Nameserver count is capped and invalid IPs are filtered; see [Configuration](#configuration).\n\n## Requirements\n\n- **Runtime**: Docker or Kubernetes.\n- **Capabilities**: `CAP_NET_ADMIN` (for the sidecar container only).\n- **Kernel**: Linux kernel with `iptables` support.\n\n## Configuration\n\n- Policy bootstrap & runtime:\n - Default deny-all. Seed initial policy via `OPENSANDBOX_EGRESS_RULES` (JSON, same shape as `/policy`); empty/`{}`/`null` stays deny-all.\n - `/policy` at runtime; empty body resets to default deny-all.\n- HTTP service:\n - Listen address: `OPENSANDBOX_EGRESS_HTTP_ADDR` (default `:18080`).\n - Auth: `OPENSANDBOX_EGRESS_TOKEN` with header `OPENSANDBOX-EGRESS-AUTH: `; if unset, endpoint is open.\n- Mode (`OPENSANDBOX_EGRESS_MODE`, default `dns`):\n - `dns`: DNS proxy only, no nftables (IP/CIDR rules have no effect at L2).\n - `dns+nft`: enable nftables; if nft apply fails, fallback to `dns`. IP/CIDR enforcement and DoH/DoT blocking require this mode.\n- **Nameserver exempt** \n Set `OPENSANDBOX_EGRESS_NAMESERVER_EXEMPT` to a comma-separated list of **nameserver IPs** (e.g. `26.26.26.26` or `26.26.26.26,100.100.2.116`). Only single IPs are supported; CIDR entries are ignored. Traffic to these IPs on port 53 is not redirected to the proxy (iptables RETURN). In `dns+nft` mode, these IPs are also merged into the nft allow set so proxy upstream traffic to them (sent without SO_MARK) is accepted. Use when the upstream is reachable only via a specific route (e.g. tunnel) and SO_MARK would send proxy traffic elsewhere.\n- **DNS and nft mode (nameserver whitelist)** \n In `dns+nft` mode, the sidecar automatically allows:\n - **127.0.0.1** โ€” so packets redirected by iptables to the proxy (127.0.0.1:15353) are accepted by nft.\n - **Nameserver IPs** from `/etc/resolv.conf` โ€” so client DNS and proxy upstream work (e.g. private DNS). \n Nameserver IPs are validated (unspecified and loopback are skipped) and capped. Use `OPENSANDBOX_EGRESS_MAX_NS` (default `3`; `0` = no cap, `1`โ€“`10` = cap). See [SECURITY-RISKS.md](SECURITY-RISKS.md) for trust and scope of this whitelist.\n- **Blocked hostname webhook** \n - `OPENSANDBOX_EGRESS_DENY_WEBHOOK`: HTTP endpoint URL. When set, egress asynchronously POSTs JSON **only when a hostname is denied**: `{\"hostname\": \"\", \"timestamp\": \"\", \"source\": \"opensandbox-egress\", \"sandboxId\": \"\"}`. Default timeout 5s, up to 3 retries with exponential backoff starting at 1s; 4xx is not retried, 5xx/network errors are retried.\n - `OPENSANDBOX_EGRESS_SANDBOX_ID`: optional sandbox identifier injected into the webhook payload as `sandboxId`. The value is read once at startup (unset โ†’ empty string).\n - **Allow requirement**: you must allow the webhook host (or its IP/CIDR) in the policy; with default deny, if you donโ€™t explicitly allow it, the webhook traffic will be blocked by egress itself. Example: `{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"webhook.example.com\"}]}`. If a broader deny CIDR covers the resolved IP, it will still be blockedโ€”adjust your policy accordingly.\n- DoH/DoT blocking:\n - DoT (tcp/udp 853) blocked by default.\n - Optional DoH over 443: `OPENSANDBOX_EGRESS_BLOCK_DOH_443=true`. If enabled without blocklist, all 443 is dropped.\n - DoH blocklist (IP/CIDR, comma-separated): `OPENSANDBOX_EGRESS_DOH_BLOCKLIST=\"9.9.9.9,1.1.1.1/32,2001:db8::/32\"`.\n\n### Runtime HTTP API\n\n- Default listen address: `:18080` (override with `OPENSANDBOX_EGRESS_HTTP_ADDR`).\n- Endpoints:\n- `GET /policy` โ€” returns the current policy.\n- `POST /policy` โ€” replaces the policy. Empty/whitespace/`{}`/`null` resets to default deny-all.\n - `PATCH /policy` โ€” merge/append rules at runtime. Body **must** be a JSON array of egress rules (not wrapped in an object). New rules are placed before existing ones (same target overrides), so a later PATCH can override prior wildcard denies with a more specific allow, and vice versa.\n\nExamples:\n\n- DNS allowlist (default deny):\n ```bash\n curl -XPOST http://127.0.0.1:18080/policy \\\n -d '{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"*.bing.com\"}]}'\n ```\n- DNS blocklist (default allow):\n ```bash\n curl -XPOST http://127.0.0.1:18080/policy \\\n -d '{\"defaultAction\":\"allow\",\"egress\":[{\"action\":\"deny\",\"target\":\"*.bing.com\"}]}'\n ```\n- IP/CIDR only:\n ```bash\n curl -XPOST http://127.0.0.1:18080/policy \\\n -d '{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"1.1.1.1\"},{\"action\":\"deny\",\"target\":\"10.0.0.0/8\"}]}'\n ```\n- Mixed DNS + IP/CIDR:\n ```bash\n curl -XPOST http://127.0.0.1:18080/policy \\\n -d '{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"*.example.com\"},{\"action\":\"allow\",\"target\":\"203.0.113.0/24\"},{\"action\":\"deny\",\"target\":\"*.bad.com\"}]}'\n ```\n- Merge-only PATCH (override wildcard deny with a specific allow):\n ```bash\n # baseline: deny *.cloudflare.com\n curl -XPOST http://127.0.0.1:18080/policy \\\n -d '{\"defaultAction\":\"allow\",\"egress\":[{\"action\":\"deny\",\"target\":\"*.cloudflare.com\"}]}'\n\n # allow a specific host; PATCH rules are prepended, so this wins\n curl -XPATCH http://127.0.0.1:18080/policy \\\n -d '[{\"action\":\"allow\",\"target\":\"www.cloudflare.com\"}]'\n ```\n\n## Build & Run\n\n### 1. Build Docker Image\n\n```bash\n# Build locally\ndocker build -t opensandbox/egress:local .\n\n# Or use the build script (multi-arch)\n./build.sh\n```\n\n### 2. Run Locally (Docker)\n\nTo test the sidecar with a sandbox application:\n\n1. **Start the Sidecar** (creates the network namespace):\n\n ```bash\n docker run -d --name sandbox-egress \\\n --cap-add=NET_ADMIN \\\n opensandbox/egress:local\n ```\n\n *Note: `CAP_NET_ADMIN` is required for `iptables` redirection.*\n\n After start, push policy via HTTP (empty body resets to deny-all):\n\n ```bash\n curl -XPOST http://11.167.84.130:18080/policy \\\n -H \"OPENSANDBOX-EGRESS-AUTH: $OPENSANDBOX_EGRESS_TOKEN\" \\\n -d '{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"*.bing.com\"}]}'\n ```\n\n2. **Start Application** (shares sidecar's network):\n\n ```bash\n docker run --rm -it \\\n --network container:sandbox-egress \\\n curlimages/curl \\\n sh\n ```\n\n3. **Verify**:\n\n Inside the application container:\n\n ```bash\n # Allowed domain\n curl -I https://google.com # Should succeed\n\n # Denied domain\n curl -I https://github.com # Should fail (resolve error)\n ```\n\n## Development\n\n- **Language**: Go 1.24+\n- **Key Packages**:\n - `pkg/dnsproxy`: DNS server and policy matching logic.\n - `pkg/iptables`: `iptables` rule management.\n - `pkg/nftables`: nftables static/dynamic rules and DNS-resolved IP sets.\n - `pkg/policy`: Policy parsing and definition.\n- **Main (egress)**:\n - `nameserver.go`: Builds the list of IPs to whitelist for DNS in nft mode (127.0.0.1 + validated/capped nameservers from resolv.conf).\n\n```bash\n# Run tests\ngo test ./...\n```\n\n### E2E benchmark: dns vs dns+nft (sync dynamic IP write)\n\nAn end-to-end benchmark compares **dns** (pass-through, no nft write) and **dns+nft** (sync `AddResolvedIPs` before each DNS reply) under real conditions: sidecar in Docker, iptables redirect, real DNS + HTTPS from a client container.\n\n```bash\n./tests/bench-dns-nft.sh\n```\n\nMore details in [docs/benchmark.md](docs/benchmark.md).\n\n## Troubleshooting\n\n- **\"iptables setup failed\"**: Ensure the sidecar container has `--cap-add=NET_ADMIN`.\n- **DNS resolution fails for all domains**: \n Check upstream reachability from the sidecar (`ip route`, `dig @ . NS +timeout=3`). In `dns+nft` mode, check logs for `[dns] whitelisting proxy listen + N nameserver(s)`.\n- **Traffic not blocked**: If nftables apply fails, the sidecar falls back to dns; check logs, `nft list table inet opensandbox`, and `CAP_NET_ADMIN`.\n" }, { "path": "components/egress/TODO.md", "content": "# Egress Sidecar TODO (Linux MVP โ†’ Full OSEP-0001)\n\n- Layer 2 still partial: static IP/CIDR now pushed to nftables, DoH/DoT blocking added (853 + optional 443 blocklist). DNS-learned IPs/dynamic isolation planned (see Short-term priorities).\n- Policy surface: IP/CIDR parsing/validation done; `require_full_isolation` and richer validation messages are out of scope (see No goals).\n- Observability missing: no violation logs.\n- Capability probing missing: no CAP_NET_ADMIN/nftables detection; hostNetwork ๅทฒ็”ฑ server ไพง้˜ปๆ–ญใ€‚ Capability detection + mode exposure moved to No goals.\n- Platform integration completed: specs/SDK/server wiring done; NET_ADMIN only on sidecar.\n- No IPv6; startup ordering not enforced (relies on container start order).\n\n## Short-term priorities (suggested order)\n1) Layer 2 via nftables \n - Tune DoH/DoT rules (ordering, allow-list exceptions, counters).\n4) Observability & logging \n - Violation logs (domain/action/upstream IP); expose current enforcement mode. \n - Optional lightweight health/status endpoint.\n6) Security hardening \n - Whitelist/validate upstream DNS to avoid arbitrary 53 egress abuse. \n - Document bypass/limits (dns-only can be bypassed via direct IP/DoH).\n7) IPv6 & tests \n - Handle IPv6 support or explicit non-support. \n - Unit/integration tests: interception, graceful degrade, nftables, DoH blocking, hostNetwork rejection.\n\n## No goals (explicitly excluded)\n- Capability probing & mode exposure (CAP_NET_ADMIN/nft detection, mode surfacing).\n- Policy expansion: `require_full_isolation` and richer validation errors.\n\n## Dev notes\n- Current behavior: default deny-all baseline even when no policy is provided; POST /policy empty resets to deny-all; env bootstrap defaults to deny-all. \n- DNS proxy always runs; SO_MARK=0x1 bypass for proxyโ€™s own upstream DNS; iptables only redirects port 53, no other DROP rules. \n- nftables: static IP/CIDR applied on start and policy update; retry without delete-table if table absent; failures fall back to DNS-only. \n- Runtime deps: Linux, `CAP_NET_ADMIN`, `iptables`/`nft` binaries; upstream DNS must be reachable and recursive.\n\n" }, { "path": "components/egress/build.sh", "content": "#!/bin/bash\n# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nset -ex\n\nTAG=${TAG:-latest}\nVERSION=${VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo \"dev\")}\nGIT_COMMIT=${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo \"unknown\")}\nBUILD_TIME=${BUILD_TIME:-$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")}\nREPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || realpath \"$(dirname \"$0\")/../..\")\ncd \"${REPO_ROOT}\"\n\ndocker buildx rm egress-builder || true\ndocker buildx create --use --name egress-builder\ndocker buildx inspect --bootstrap\ndocker buildx ls\n\nLATEST_TAGS=()\nif [[ \"${TAG}\" == v* ]]; then\n LATEST_TAGS+=(-t opensandbox/egress:latest -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:latest)\nfi\n\ndocker buildx build \\\n -t opensandbox/egress:${TAG} \\\n -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:${TAG} \\\n \"${LATEST_TAGS[@]}\" \\\n -f components/egress/Dockerfile \\\n --build-arg VERSION=\"${VERSION}\" \\\n --build-arg GIT_COMMIT=\"${GIT_COMMIT}\" \\\n --build-arg BUILD_TIME=\"${BUILD_TIME}\" \\\n --platform linux/amd64,linux/arm64 \\\n --push \\\n .\n" }, { "path": "components/egress/docs/benchmark.md", "content": "# Egress Benchmark\n\nThis document describes the **Egress Sidecar** end-to-end benchmark: it compares **dns** and **dns+nft** modes under real conditions for latency and throughput.\n\n## Purpose\n\n- **dns**: DNS proxy only (pass-through), no nftables writes; used as the baseline.\n- **dns+nft**: DNS proxy plus synchronous `AddResolvedIPs` before each DNS reply, writing resolved IPs into nftables for\n L2 egress enforcement.\n\nThe benchmark runs the same workload in both modes and reports end-to-end latency (P50, P99) and throughput (Req/s) to\nmeasure the overhead of the synchronous nft write path.\n\n## Environment and Flow\n\n- **Environment**: The Egress sidecar runs in a Docker container on the host. The container includes the sidecar (DNS\n proxy and optional nft), iptables redirect of port 53 to the proxy, and the policy server on port 18080. The workload\n runs **inside the same container**: DNS and HTTPS traffic go through the proxy.\n- **Flow** (per phase):\n 1. Start the sidecar with the chosen mode (`dns` or `dns+nft`).\n 2. Wait for health checks, then push the allow list to `/policy` (see domain list below).\n 3. Write the domain list into the container as `/tmp/bench-domains.txt` (one `https://` per line).\n 4. **Warm-up**: One request to each of the first 10 domains (10 concurrent), 1 round.\n 5. **Timed run**: One request per domain for all domains (N concurrent per round), for 10 rounds; each request\n records `time_namelookup` and `time_total`.\n 6. Copy results from the container and compute P50, P99, average latency, and Req/s.\n- **Execution order**: **dns+nft** runs first, then **dns**; the comparison table is printed at the end.\n\n## Workload\n\n- **Domain list**: Read from `components/egress/tests/hostname.txt`, one domain per line (lines starting with `#` and\n empty lines are ignored). Default is about 100 resolvable domains.\n- **Rounds and concurrency**: The script uses `ROUNDS=10`. Each round issues one HTTPS request per domain in\n `hostname.txt`, with all requests in that round concurrent; 10 rounds total.\n- **Total requests**: `TOTAL_REQUESTS = ROUNDS ร— NUM_DOMAINS` (e.g. 10 ร— 100 = 1000).\n- **Per request**: Inside the container, `curl -o /dev/null -s -w \"%{time_namelookup}\\t%{time_total}\\n\"` is used against\n `https://`, with a 10s timeout per request; the whole benchmark run has a 300s wall-clock timeout.\n\n## Policy\n\n- Policy is default-deny with explicit allow rules: one `{\"action\":\"allow\",\"target\":\"\"}` per domain in\n `hostname.txt` is sent via `POST /policy`, so every domain used in the benchmark is allowed.\n\n## How to Run\n\n**Script**: `components/egress/tests/bench-e2e-dns-nft.sh`\n\n**Requirements**: Docker and `curl` on the host (for pushing policy); the Egress image includes `curl` for the workload.\n\n**Commands** (from repo root or from `components/egress`):\n\n```bash\n./tests/bench-dns-nft.sh\n```\n\nThe script resolves `tests/hostname.txt` relative to its own path, so the working directory does not need to be changed.\n\n## Configuration\n\n| Item | Location / variable | Default / notes |\n|---------------------|----------------------------------------|------------------------------------------------|\n| Domain list | `components/egress/tests/hostname.txt` | One domain per line; `#` comments allowed |\n| Rounds | `ROUNDS` in script | 10 |\n| Per-request timeout | `CURL_TIMEOUT` in script | 10 seconds |\n| Benchmark timeout | `BENCH_EXEC_TIMEOUT` in script | 300 seconds (max wall time for the timed run) |\n| Image | `IMG` in script | See script; override for a locally built image |\n\nChanging the number of domains or rounds updates the total request count; the report shows โ€œN rounds ร— M domainsโ€ for\nthe current config.\n\n## Output and Metrics\n\n- **Terminal**: A table with **Req/s**, **Avg(s)**, **P50(s)**, **P99(s)** for both modes, plus short notes (dns vs\n dns+nft, warm-up, first-resolution cost).\n- **Artifacts** (on the host under `/tmp`): `bench-e2e-dns-total.txt`, `bench-e2e-dns+nft-total.txt` (one\n `time_total` per line), and `-namelookup.txt`, `-wall.txt`, etc., for further analysis or plotting.\n\n## Notes\n\n- The first resolution of a domain in dns+nft triggers a DNS lookup and an nft write, so cost is higher; later requests\n for the same domain hit the set and are cheaper. The multi-round, multi-domain design mixes cold and warm resolution.\n- In CI (e.g. GitHub Actions), the script wraps the timed-run `docker exec` with `timeout` inside the shell function so\n `timeout` runs a real command, not a function name, avoiding โ€œNo such file or directoryโ€ errors.\n" }, { "path": "components/egress/go.mod", "content": "module github.com/alibaba/opensandbox/egress\n\ngo 1.24.0\n\nrequire (\n\tgithub.com/alibaba/opensandbox/internal v0.0.0\n\tgithub.com/miekg/dns v1.1.61\n\tgithub.com/stretchr/testify v1.11.1\n\tgolang.org/x/sys v0.31.0\n)\n\nrequire (\n\tgithub.com/davecgh/go-spew v1.1.1 // indirect\n\tgithub.com/pmezard/go-difflib v1.0.0 // indirect\n\tgo.uber.org/multierr v1.10.0 // indirect\n\tgo.uber.org/zap v1.27.0 // indirect\n\tgolang.org/x/mod v0.18.0 // indirect\n\tgolang.org/x/net v0.38.0 // indirect\n\tgolang.org/x/sync v0.7.0 // indirect\n\tgolang.org/x/tools v0.22.0 // indirect\n\tgopkg.in/yaml.v3 v3.0.1 // indirect\n)\n\nreplace github.com/alibaba/opensandbox/internal => ../internal\n" }, { "path": "components/egress/go.sum", "content": "github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=\ngithub.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=\ngithub.com/miekg/dns v1.1.61 h1:nLxbwF3XxhwVSm8g9Dghm9MHPaUZuqhPiGL+675ZmEs=\ngithub.com/miekg/dns v1.1.61/go.mod h1:mnAarhS3nWaW+NVP2wTkYVIZyHNJ098SJZUki3eykwQ=\ngithub.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=\ngithub.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=\ngithub.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=\ngithub.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=\ngo.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=\ngo.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=\ngo.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=\ngo.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=\ngo.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=\ngo.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=\ngolang.org/x/mod v0.18.0 h1:5+9lSbEzPSdWkH32vYPBwEpX8KwDbM52Ud9xBUvNlb0=\ngolang.org/x/mod v0.18.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=\ngolang.org/x/net v0.38.0 h1:vRMAPTMaeGqVhG5QyLJHqNDwecKTomGeqbnfZyKlBI8=\ngolang.org/x/net v0.38.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=\ngolang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M=\ngolang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=\ngolang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=\ngolang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=\ngolang.org/x/tools v0.22.0 h1:gqSGLZqv+AI9lIQzniJ0nZDRG5GBPsSi+DRNHWNz6yA=\ngolang.org/x/tools v0.22.0/go.mod h1:aCwcsjqvq7Yqt6TNyX7QMU2enbQ/Gt0bo6krSeEri+c=\ngopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=\ngopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=\ngopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=\ngopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=\n" }, { "path": "components/egress/main.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"context\"\n\t\"net/netip\"\n\t\"os\"\n\t\"os/signal\"\n\t\"strings\"\n\t\"syscall\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/dnsproxy\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/events\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/iptables\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n\t\"github.com/alibaba/opensandbox/internal/version\"\n)\n\nfunc main() {\n\tversion.EchoVersion(\"OpenSandbox Egress\")\n\n\tctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)\n\tdefer cancel()\n\n\tctx = withLogger(ctx)\n\tdefer log.Logger.Sync()\n\n\tinitialRules, err := dnsproxy.LoadPolicyFromEnvVar(constants.EnvEgressRules)\n\tif err != nil {\n\t\tlog.Fatalf(\"failed to parse %s: %v\", constants.EnvEgressRules, err)\n\t}\n\n\tallowIPs := AllowIPsForNft(\"/etc/resolv.conf\")\n\t// Merge nameserver exempt IPs into nft allow set so proxy traffic to them (no SO_MARK) is allowed in dns+nft mode.\n\tfor _, addr := range dnsproxy.ParseNameserverExemptList() {\n\t\tif !containsAddr(allowIPs, addr) {\n\t\t\tallowIPs = append(allowIPs, addr)\n\t\t}\n\t}\n\n\tmode := parseMode()\n\tlog.Infof(\"enforcement mode: %s\", mode)\n\tnftMgr := createNftManager(mode)\n\tproxy, err := dnsproxy.New(initialRules, \"\")\n\tif err != nil {\n\t\tlog.Fatalf(\"failed to init dns proxy: %v\", err)\n\t}\n\tif err := proxy.Start(ctx); err != nil {\n\t\tlog.Fatalf(\"failed to start dns proxy: %v\", err)\n\t}\n\tlog.Infof(\"dns proxy started on 127.0.0.1:15353\")\n\n\tif blockWebhookURL := strings.TrimSpace(os.Getenv(constants.EnvBlockedWebhook)); blockWebhookURL != \"\" {\n\t\tblockedBroadcaster := events.NewBroadcaster(ctx, events.BroadcasterConfig{QueueSize: 256})\n\t\tblockedBroadcaster.AddSubscriber(events.NewWebhookSubscriber(blockWebhookURL))\n\t\tproxy.SetBlockedBroadcaster(blockedBroadcaster)\n\t\tdefer blockedBroadcaster.Close()\n\t\tlog.Infof(\"denied hostname webhook enabled\")\n\t}\n\n\texemptDst := dnsproxy.ParseNameserverExemptList()\n\tif len(exemptDst) > 0 {\n\t\tlog.Infof(\"nameserver exempt list: %v (proxy upstream in this list will not set SO_MARK)\", exemptDst)\n\t}\n\tif err := iptables.SetupRedirect(15353, exemptDst); err != nil {\n\t\tlog.Fatalf(\"failed to install iptables redirect: %v\", err)\n\t}\n\tlog.Infof(\"iptables redirect configured (OUTPUT 53 -> 15353) with SO_MARK bypass for proxy upstream traffic\")\n\n\tsetupNft(ctx, nftMgr, initialRules, proxy, allowIPs)\n\n\t// start policy server\n\thttpAddr := envOrDefault(constants.EnvEgressHTTPAddr, constants.DefaultEgressServerAddr)\n\tif err = startPolicyServer(ctx, proxy, nftMgr, mode, httpAddr, os.Getenv(constants.EnvEgressToken), allowIPs); err != nil {\n\t\tlog.Fatalf(\"failed to start policy server: %v\", err)\n\t}\n\tlog.Infof(\"policy server listening on %s (POST /policy)\", httpAddr)\n\n\t<-ctx.Done()\n\tlog.Infof(\"received shutdown signal; exiting\")\n\t_ = os.Stderr.Sync()\n}\n\nfunc withLogger(ctx context.Context) context.Context {\n\tlevel := envOrDefault(constants.EnvEgressLogLevel, \"info\")\n\tlogger := slogger.MustNew(slogger.Config{Level: level}).Named(\"opensandbox.egress\")\n\treturn log.WithLogger(ctx, logger)\n}\n\nfunc envOrDefault(key, defaultVal string) string {\n\tif v := strings.TrimSpace(os.Getenv(key)); v != \"\" {\n\t\treturn v\n\t}\n\treturn defaultVal\n}\n\nfunc isTruthy(v string) bool {\n\tswitch strings.ToLower(strings.TrimSpace(v)) {\n\tcase \"1\", \"true\", \"yes\", \"y\", \"on\":\n\t\treturn true\n\tdefault:\n\t\treturn false\n\t}\n}\n\nfunc containsAddr(addrs []netip.Addr, a netip.Addr) bool {\n\tfor _, x := range addrs {\n\t\tif x == a {\n\t\t\treturn true\n\t\t}\n\t}\n\treturn false\n}\n\nfunc parseMode() string {\n\tmode := strings.ToLower(strings.TrimSpace(os.Getenv(constants.EnvEgressMode)))\n\tswitch mode {\n\tcase \"\", constants.PolicyDnsOnly:\n\t\treturn constants.PolicyDnsOnly\n\tcase constants.PolicyDnsNft:\n\t\treturn constants.PolicyDnsNft\n\tdefault:\n\t\tlog.Warnf(\"invalid %s=%s, falling back to dns\", constants.EnvEgressMode, mode)\n\t\treturn constants.PolicyDnsOnly\n\t}\n}\n" }, { "path": "components/egress/nameserver.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"net/netip\"\n\t\"os\"\n\t\"strconv\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/dnsproxy\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n)\n\n// AllowIPsForNft returns the list of IPs to merge into the nft allow set for DNS in dns+nft mode:\n// 127.0.0.1 (proxy listen / iptables redirect target) plus validated, capped nameserver IPs from resolvPath.\n// Validation: skips unspecified (0.0.0.0, ::) and loopback (127.x, ::1).\n// Cap: at most max nameservers (default 3; set EGRESS_MAX_NAMESERVERS=0 for no cap, or 1โ€“10).\nfunc AllowIPsForNft(resolvPath string) []netip.Addr {\n\traw, _ := dnsproxy.ResolvNameserverIPs(resolvPath)\n\tmaxNsCount := maxNameserversFromEnv()\n\n\tvar validated []netip.Addr\n\tfor _, ip := range raw {\n\t\tif maxNsCount > 0 && len(validated) >= maxNsCount {\n\t\t\tbreak\n\t\t}\n\t\tif !isValidNameserverIP(ip) {\n\t\t\tcontinue\n\t\t}\n\t\tvalidated = append(validated, ip)\n\t}\n\n\t// 127.0.0.1 first so packets redirected to proxy are accepted by nft.\n\tout := make([]netip.Addr, 0, 1+len(validated))\n\tout = append(out, netip.MustParseAddr(\"127.0.0.1\"))\n\tout = append(out, validated...)\n\n\tif len(out) > 1 {\n\t\tlog.Infof(\"[dns] whitelisting proxy listen + %d nameserver(s) for nft: %v\", len(validated), formatIPs(out))\n\t} else {\n\t\tlog.Infof(\"[dns] whitelisting proxy listen (127.0.0.1); no valid nameserver IPs from %s\", resolvPath)\n\t}\n\treturn out\n}\n\nfunc maxNameserversFromEnv() int {\n\ts := os.Getenv(constants.EnvMaxNameservers)\n\tif s == \"\" {\n\t\treturn constants.DefaultMaxNameservers\n\t}\n\tn, err := strconv.Atoi(s)\n\tif err != nil || n < 0 {\n\t\treturn constants.DefaultMaxNameservers\n\t}\n\tif n > 10 {\n\t\treturn 10\n\t}\n\t// 0 = no cap\n\treturn n\n}\n\nfunc isValidNameserverIP(ip netip.Addr) bool {\n\tif ip.IsUnspecified() {\n\t\treturn false\n\t}\n\tif ip.IsLoopback() {\n\t\treturn false\n\t}\n\treturn true\n}\n\nfunc formatIPs(ips []netip.Addr) []string {\n\tout := make([]string, len(ips))\n\tfor i, ip := range ips {\n\t\tout[i] = ip.String()\n\t}\n\treturn out\n}\n" }, { "path": "components/egress/nameserver_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"net/netip\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestAllowIPsForNft_EmptyResolv(t *testing.T) {\n\tdir := t.TempDir()\n\tresolv := filepath.Join(dir, \"resolv.conf\")\n\trequire.NoError(t, os.WriteFile(resolv, []byte(\"# empty\\n\"), 0644))\n\tips := AllowIPsForNft(resolv)\n\trequire.Len(t, ips, 1, \"expected 1 IP (127.0.0.1)\")\n\trequire.Equal(t, netip.MustParseAddr(\"127.0.0.1\"), ips[0])\n}\n\nfunc TestAllowIPsForNft_ValidNameservers(t *testing.T) {\n\tdir := t.TempDir()\n\tresolv := filepath.Join(dir, \"resolv.conf\")\n\t// Standard resolv.conf with two nameservers\n\tcontent := \"nameserver 192.168.65.7\\nnameserver 10.0.0.1\\n\"\n\trequire.NoError(t, os.WriteFile(resolv, []byte(content), 0644))\n\tips := AllowIPsForNft(resolv)\n\trequire.Len(t, ips, 3, \"expected 3 IPs (127.0.0.1 + 2 nameservers)\")\n\trequire.Equal(t, netip.MustParseAddr(\"127.0.0.1\"), ips[0], \"expected first 127.0.0.1\")\n\trequire.Equal(t, netip.MustParseAddr(\"192.168.65.7\"), ips[1], \"expected 192.168.65.7\")\n\trequire.Equal(t, netip.MustParseAddr(\"10.0.0.1\"), ips[2], \"expected 10.0.0.1\")\n}\n\nfunc TestAllowIPsForNft_FiltersInvalid(t *testing.T) {\n\tdir := t.TempDir()\n\tresolv := filepath.Join(dir, \"resolv.conf\")\n\t// 0.0.0.0 and 127.0.0.11 should be filtered; 192.168.1.1 kept\n\tcontent := \"nameserver 0.0.0.0\\nnameserver 192.168.1.1\\nnameserver 127.0.0.11\\n\"\n\trequire.NoError(t, os.WriteFile(resolv, []byte(content), 0644))\n\tips := AllowIPsForNft(resolv)\n\trequire.Len(t, ips, 2, \"expected 2 IPs (127.0.0.1 + 192.168.1.1)\")\n\trequire.Equal(t, netip.MustParseAddr(\"127.0.0.1\"), ips[0], \"expected first 127.0.0.1\")\n\trequire.Equal(t, netip.MustParseAddr(\"192.168.1.1\"), ips[1], \"expected 192.168.1.1\")\n}\n\nfunc TestAllowIPsForNft_Cap(t *testing.T) {\n\tdir := t.TempDir()\n\tresolv := filepath.Join(dir, \"resolv.conf\")\n\tcontent := \"nameserver 10.0.0.1\\nnameserver 10.0.0.2\\nnameserver 10.0.0.3\\nnameserver 10.0.0.4\\n\"\n\trequire.NoError(t, os.WriteFile(resolv, []byte(content), 0644))\n\told := os.Getenv(constants.EnvMaxNameservers)\n\tdefer os.Setenv(constants.EnvMaxNameservers, old)\n\tos.Setenv(constants.EnvMaxNameservers, \"2\")\n\n\tips := AllowIPsForNft(resolv)\n\t// 127.0.0.1 + 2 nameservers (cap)\n\trequire.Len(t, ips, 3, \"expected 3 IPs (127.0.0.1 + 2 capped)\")\n\trequire.Equal(t, netip.MustParseAddr(\"10.0.0.1\"), ips[1], \"expected first nameserver to be 10.0.0.1\")\n\trequire.Equal(t, netip.MustParseAddr(\"10.0.0.2\"), ips[2], \"expected second nameserver to be 10.0.0.2\")\n}\n\nfunc TestIsValidNameserverIP(t *testing.T) {\n\ttests := []struct {\n\t\tip string\n\t\twant bool\n\t}{\n\t\t{\"0.0.0.0\", false},\n\t\t{\"::\", false},\n\t\t{\"127.0.0.1\", false},\n\t\t{\"127.0.0.11\", false},\n\t\t{\"::1\", false},\n\t\t{\"192.168.65.7\", true},\n\t\t{\"10.0.0.1\", true},\n\t\t{\"8.8.8.8\", true},\n\t}\n\tfor _, tt := range tests {\n\t\tip := netip.MustParseAddr(tt.ip)\n\t\tgot := isValidNameserverIP(ip)\n\t\tif got != tt.want {\n\t\t\tt.Errorf(\"isValidNameserverIP(%s) = %v, want %v\", tt.ip, got, tt.want)\n\t\t}\n\t}\n}\n\nfunc TestMaxNameserversFromEnv(t *testing.T) {\n\told := os.Getenv(constants.EnvMaxNameservers)\n\tdefer os.Setenv(constants.EnvMaxNameservers, old)\n\n\tfor _, s := range []string{\"\", \"x\", \"-1\"} {\n\t\tos.Setenv(constants.EnvMaxNameservers, s)\n\t\tif got := maxNameserversFromEnv(); got != constants.DefaultMaxNameservers {\n\t\t\tt.Errorf(\"maxNameserversFromEnv(%q) = %d, want default %d\", s, got, constants.DefaultMaxNameservers)\n\t\t}\n\t}\n\tos.Setenv(constants.EnvMaxNameservers, \"0\")\n\tif got := maxNameserversFromEnv(); got != 0 {\n\t\tt.Errorf(\"maxNameserversFromEnv(0) = %d, want 0\", got)\n\t}\n\tos.Setenv(constants.EnvMaxNameservers, \"5\")\n\tif got := maxNameserversFromEnv(); got != 5 {\n\t\tt.Errorf(\"maxNameserversFromEnv(5) = %d, want 5\", got)\n\t}\n\tos.Setenv(constants.EnvMaxNameservers, \"99\")\n\tif got := maxNameserversFromEnv(); got != 10 {\n\t\tt.Errorf(\"maxNameserversFromEnv(99) = %d, want 10 (capped)\", got)\n\t}\n}\n" }, { "path": "components/egress/nft.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"context\"\n\t\"net/netip\"\n\t\"os\"\n\t\"strings\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/dnsproxy\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/nftables\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/policy\"\n)\n\n// createNftManager returns an nft manager for dns+nft mode, or nil for dns-only.\nfunc createNftManager(mode string) nftApplier {\n\tif mode != constants.PolicyDnsNft {\n\t\treturn nil\n\t}\n\treturn nftables.NewManagerWithOptions(parseNftOptions())\n}\n\n// setupNft applies static policy to nft and wires DNS-resolved IPs into the proxy when nft is enabled.\n// nameserverIPs are merged into the allow set at startup so system DNS works (client + proxy upstream, e.g. private DNS).\nfunc setupNft(ctx context.Context, nftMgr nftApplier, initialPolicy *policy.NetworkPolicy, proxy *dnsproxy.Proxy, nameserverIPs []netip.Addr) {\n\tif nftMgr == nil {\n\t\tlog.Warnf(\"nftables disabled (dns-only mode)\")\n\t\treturn\n\t}\n\tlog.Infof(\"applying nftables static policy (dns+nft mode) with %d nameserver IP(s) merged into allow set\", len(nameserverIPs))\n\tpolicyWithNS := initialPolicy.WithExtraAllowIPs(nameserverIPs)\n\tif err := nftMgr.ApplyStatic(ctx, policyWithNS); err != nil {\n\t\tlog.Fatalf(\"nftables static apply failed: %v\", err)\n\t}\n\tlog.Infof(\"nftables static policy applied (table inet opensandbox); DNS-resolved IPs will be added to dynamic allow sets\")\n\tproxy.SetOnResolved(func(domain string, ips []nftables.ResolvedIP) {\n\t\tif err := nftMgr.AddResolvedIPs(ctx, ips); err != nil {\n\t\t\tlog.Warnf(\"[dns] add resolved IPs to nft failed for domain %q: %v\", domain, err)\n\t\t}\n\t})\n}\n\nfunc parseNftOptions() nftables.Options {\n\topts := nftables.Options{BlockDoT: true}\n\tif isTruthy(os.Getenv(constants.EnvBlockDoH443)) {\n\t\topts.BlockDoH443 = true\n\t}\n\tif raw := os.Getenv(constants.EnvDoHBlocklist); strings.TrimSpace(raw) != \"\" {\n\t\tparts := strings.Split(raw, \",\")\n\t\tfor _, p := range parts {\n\t\t\ttarget := strings.TrimSpace(p)\n\t\t\tif target == \"\" {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif addr, err := netip.ParseAddr(target); err == nil {\n\t\t\t\tif addr.Is4() {\n\t\t\t\t\topts.DoHBlocklistV4 = append(opts.DoHBlocklistV4, target)\n\t\t\t\t} else if addr.Is6() {\n\t\t\t\t\topts.DoHBlocklistV6 = append(opts.DoHBlocklistV6, target)\n\t\t\t\t}\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif prefix, err := netip.ParsePrefix(target); err == nil {\n\t\t\t\tif prefix.Addr().Is4() {\n\t\t\t\t\topts.DoHBlocklistV4 = append(opts.DoHBlocklistV4, target)\n\t\t\t\t} else if prefix.Addr().Is6() {\n\t\t\t\t\topts.DoHBlocklistV6 = append(opts.DoHBlocklistV6, target)\n\t\t\t\t}\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tlog.Warnf(\"ignoring invalid DoH blocklist entry: %s\", target)\n\t\t}\n\t}\n\treturn opts\n}\n" }, { "path": "components/egress/pkg/constants/configuration.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage constants\n\nconst (\n\tEnvBlockDoH443 = \"OPENSANDBOX_EGRESS_BLOCK_DOH_443\"\n\tEnvDoHBlocklist = \"OPENSANDBOX_EGRESS_DOH_BLOCKLIST\" // comma-separated IP/CIDR\n\tEnvEgressMode = \"OPENSANDBOX_EGRESS_MODE\" // dns | dns+nft\n\tEnvEgressHTTPAddr = \"OPENSANDBOX_EGRESS_HTTP_ADDR\"\n\tEnvEgressToken = \"OPENSANDBOX_EGRESS_TOKEN\"\n\tEnvEgressRules = \"OPENSANDBOX_EGRESS_RULES\"\n\tEnvEgressLogLevel = \"OPENSANDBOX_EGRESS_LOG_LEVEL\"\n\tEnvMaxNameservers = \"OPENSANDBOX_EGRESS_MAX_NS\"\n\tEnvBlockedWebhook = \"OPENSANDBOX_EGRESS_DENY_WEBHOOK\"\n\tENVSandboxID = \"OPENSANDBOX_EGRESS_SANDBOX_ID\"\n\n\t// EnvNameserverExempt comma-separated IPs; proxy upstream to these is not marked and is allowed in nft allow set\n\tEnvNameserverExempt = \"OPENSANDBOX_EGRESS_NAMESERVER_EXEMPT\"\n)\n\nconst (\n\tPolicyDnsOnly = \"dns\"\n\tPolicyDnsNft = \"dns+nft\"\n)\n\nconst (\n\tDefaultEgressServerAddr = \":18080\"\n\tDefaultMaxNameservers = 3\n)\n" }, { "path": "components/egress/pkg/constants/constants.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage constants\n\nconst (\n\tMarkValue = 0x1\n\tMarkHex = \"0x1\"\n)\n\nconst (\n\tEgressAuthTokenHeader = \"OPENSANDBOX-EGRESS-AUTH\"\n)\n" }, { "path": "components/egress/pkg/dnsproxy/exempt.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage dnsproxy\n\nimport (\n\t\"net/netip\"\n\t\"os\"\n\t\"strings\"\n\t\"sync\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n)\n\nvar (\n\texemptListOnce sync.Once\n\texemptAddrs []netip.Addr\n\texemptSet map[netip.Addr]struct{}\n)\n\n// ParseNameserverExemptList returns IPs from OPENSANDBOX_EGRESS_NAMESERVER_EXEMPT (comma-separated).\n// Only single IPs are accepted; invalid or CIDR entries are skipped. Result is cached. Used for nft allow set, iptables, and UpstreamInExemptList.\nfunc ParseNameserverExemptList() []netip.Addr {\n\texemptListOnce.Do(func() { parseNameserverExemptListUncached() })\n\treturn exemptAddrs\n}\n\nfunc parseNameserverExemptListUncached() {\n\traw := strings.TrimSpace(os.Getenv(constants.EnvNameserverExempt))\n\tif raw == \"\" {\n\t\texemptAddrs = nil\n\t\texemptSet = nil\n\t\treturn\n\t}\n\tset := make(map[netip.Addr]struct{})\n\tvar out []netip.Addr\n\tfor _, s := range strings.Split(raw, \",\") {\n\t\ts = strings.TrimSpace(s)\n\t\tif s == \"\" {\n\t\t\tcontinue\n\t\t}\n\t\tif addr, err := netip.ParseAddr(s); err == nil {\n\t\t\tif _, exists := set[addr]; exists {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tset[addr] = struct{}{}\n\t\t\tout = append(out, addr)\n\t\t}\n\t}\n\texemptAddrs = out\n\texemptSet = set\n}\n\n// UpstreamInExemptList returns true when upstreamHost is in the nameserver exempt list (exact IP match).\n// When true, the proxy should not set SO_MARK so upstream traffic follows normal routing (e.g. via tun).\nfunc UpstreamInExemptList(upstreamHost string) bool {\n\taddr, err := netip.ParseAddr(upstreamHost)\n\tif err != nil {\n\t\treturn false\n\t}\n\tParseNameserverExemptList() // ensure cache is initialized\n\t_, ok := exemptSet[addr]\n\treturn ok\n}\n" }, { "path": "components/egress/pkg/dnsproxy/exempt_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage dnsproxy\n\nimport (\n\t\"net/netip\"\n\t\"sync\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc resetNameserverExemptCache(t *testing.T) {\n\tt.Helper()\n\texemptAddrs = nil\n\texemptSet = nil\n\texemptListOnce = sync.Once{}\n}\n\nfunc TestParseNameserverExemptList_IPOnly(t *testing.T) {\n\tt.Setenv(constants.EnvNameserverExempt, \"1.1.1.1, 2001:db8::1 ,invalid, 10.0.0.0/8, ,\")\n\tresetNameserverExemptCache(t)\n\n\tgot := ParseNameserverExemptList()\n\twant := []netip.Addr{netip.MustParseAddr(\"1.1.1.1\"), netip.MustParseAddr(\"2001:db8::1\")}\n\trequire.Equal(t, want, got, \"ParseNameserverExemptList() mismatch\")\n\n\t// Cached result should stay the same on subsequent calls.\n\trequire.Equal(t, want, ParseNameserverExemptList(), \"cached ParseNameserverExemptList() mismatch\")\n}\n\nfunc TestUpstreamInExemptList_IPOnly(t *testing.T) {\n\tt.Setenv(constants.EnvNameserverExempt, \"1.1.1.1,2001:db8::1\")\n\tresetNameserverExemptCache(t)\n\n\trequire.True(t, UpstreamInExemptList(\"1.1.1.1\"), \"expected IPv4 upstream to be exempt\")\n\trequire.True(t, UpstreamInExemptList(\"2001:db8::1\"), \"expected IPv6 upstream to be exempt\")\n\trequire.False(t, UpstreamInExemptList(\"10.0.0.2\"), \"unexpected exempt match for non-listed IP\")\n\trequire.False(t, UpstreamInExemptList(\"not-an-ip\"), \"invalid IP string should not match\")\n}\n\nfunc TestUpstreamInExemptList_CIDRIgnored(t *testing.T) {\n\tt.Setenv(constants.EnvNameserverExempt, \"10.0.0.0/24\")\n\tresetNameserverExemptCache(t)\n\n\trequire.Empty(t, ParseNameserverExemptList(), \"CIDR should be ignored in exempt list\")\n\trequire.False(t, UpstreamInExemptList(\"10.0.0.5\"), \"CIDR should not make upstream exempt\")\n}\n" }, { "path": "components/egress/pkg/dnsproxy/proxy.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage dnsproxy\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"net\"\n\t\"net/netip\"\n\t\"os\"\n\t\"strings\"\n\t\"sync\"\n\t\"time\"\n\n\t\"github.com/miekg/dns\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/events\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/nftables\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/policy\"\n)\n\nconst defaultListenAddr = \"127.0.0.1:15353\"\n\ntype Proxy struct {\n\tpolicyMu sync.RWMutex\n\tpolicy *policy.NetworkPolicy\n\tlistenAddr string\n\tupstream string // single upstream for MVP\n\tservers []*dns.Server\n\n\t// optional; called in goroutine when A/AAAA are present\n\tonResolved func(domain string, ips []nftables.ResolvedIP)\n\n\t// optional broadcaster to notify blocked hostnames\n\tblockedBroadcaster *events.Broadcaster\n}\n\n// New builds a proxy with resolved upstream; listenAddr can be empty for default.\nfunc New(p *policy.NetworkPolicy, listenAddr string) (*Proxy, error) {\n\tif listenAddr == \"\" {\n\t\tlistenAddr = defaultListenAddr\n\t}\n\tif p == nil {\n\t\tp = policy.DefaultDenyPolicy()\n\t}\n\tupstream, err := discoverUpstream()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tproxy := &Proxy{\n\t\tlistenAddr: listenAddr,\n\t\tupstream: upstream,\n\t\tpolicy: ensurePolicyDefaults(p),\n\t}\n\treturn proxy, nil\n}\n\nfunc (p *Proxy) Start(ctx context.Context) error {\n\thandler := dns.HandlerFunc(p.serveDNS)\n\n\tudpServer := &dns.Server{Addr: p.listenAddr, Net: \"udp\", Handler: handler}\n\ttcpServer := &dns.Server{Addr: p.listenAddr, Net: \"tcp\", Handler: handler}\n\tp.servers = []*dns.Server{udpServer, tcpServer}\n\n\terrCh := make(chan error, len(p.servers))\n\tfor _, srv := range p.servers {\n\t\ts := srv\n\t\tgo func() {\n\t\t\tif err := s.ListenAndServe(); err != nil {\n\t\t\t\terrCh <- err\n\t\t\t}\n\t\t}()\n\t}\n\n\t// Shutdown on context done\n\tgo func() {\n\t\t<-ctx.Done()\n\t\tfor _, srv := range p.servers {\n\t\t\t_ = srv.Shutdown()\n\t\t}\n\t}()\n\n\tselect {\n\tcase err := <-errCh:\n\t\treturn fmt.Errorf(\"dns proxy failed: %w\", err)\n\tcase <-time.After(200 * time.Millisecond):\n\t\t// small grace window; running fine\n\t\treturn nil\n\t}\n}\n\nfunc (p *Proxy) serveDNS(w dns.ResponseWriter, r *dns.Msg) {\n\tif len(r.Question) == 0 {\n\t\t_ = w.WriteMsg(new(dns.Msg)) // empty response\n\t\treturn\n\t}\n\tq := r.Question[0]\n\tdomain := q.Name\n\n\tp.policyMu.RLock()\n\tcurrentPolicy := p.policy\n\tp.policyMu.RUnlock()\n\tif currentPolicy != nil && currentPolicy.Evaluate(domain) == policy.ActionDeny {\n\t\tp.publishBlocked(domain)\n\t\tresp := new(dns.Msg)\n\t\tresp.SetRcode(r, dns.RcodeNameError)\n\t\t_ = w.WriteMsg(resp)\n\t\treturn\n\t}\n\n\tresp, err := p.forward(r)\n\tif err != nil {\n\t\tlog.Warnf(\"[dns] forward error for %s: %v\", domain, err)\n\t\tfail := new(dns.Msg)\n\t\tfail.SetRcode(r, dns.RcodeServerFailure)\n\t\t_ = w.WriteMsg(fail)\n\t\treturn\n\t}\n\tp.maybeNotifyResolved(domain, resp)\n\t_ = w.WriteMsg(resp)\n}\n\n// maybeNotifyResolved calls onResolved synchronously when resp contains A/AAAA,\n// so that IPs are in nft before the client receives the DNS response and connects.\nfunc (p *Proxy) maybeNotifyResolved(domain string, resp *dns.Msg) {\n\tif p.onResolved == nil {\n\t\treturn\n\t}\n\tips := extractResolvedIPs(resp)\n\tif len(ips) == 0 {\n\t\treturn\n\t}\n\tp.onResolved(domain, ips)\n}\n\nfunc (p *Proxy) forward(r *dns.Msg) (*dns.Msg, error) {\n\tc := &dns.Client{\n\t\tTimeout: 5 * time.Second,\n\t\tDialer: p.dialerWithMark(),\n\t}\n\tresp, _, err := c.Exchange(r, p.upstream)\n\treturn resp, err\n}\n\n// UpstreamHost returns the host part of the upstream resolver, empty on parse error.\nfunc (p *Proxy) UpstreamHost() string {\n\thost, _, err := net.SplitHostPort(p.upstream)\n\tif err != nil {\n\t\treturn \"\"\n\t}\n\treturn host\n}\n\n// UpdatePolicy swaps the in-memory policy used by the proxy.\n// Passing nil reverts to the default deny-all policy.\nfunc (p *Proxy) UpdatePolicy(newPolicy *policy.NetworkPolicy) {\n\tp.policyMu.Lock()\n\tp.policy = ensurePolicyDefaults(newPolicy)\n\tp.policyMu.Unlock()\n}\n\n// CurrentPolicy returns the policy currently enforced by the proxy.\nfunc (p *Proxy) CurrentPolicy() *policy.NetworkPolicy {\n\tp.policyMu.RLock()\n\tdefer p.policyMu.RUnlock()\n\treturn p.policy\n}\n\n// SetOnResolved sets the callback invoked when an allowed domain resolves to A/AAAA.\n// Called in a goroutine; pass nil to disable. Only used when L2 dynamic IP is enabled (e.g. dns+nft mode).\nfunc (p *Proxy) SetOnResolved(fn func(domain string, ips []nftables.ResolvedIP)) {\n\tp.onResolved = fn\n}\n\n// SetBlockedBroadcaster wires a broadcaster used to notify blocked hostnames.\nfunc (p *Proxy) SetBlockedBroadcaster(b *events.Broadcaster) {\n\tp.blockedBroadcaster = b\n}\n\nfunc (p *Proxy) publishBlocked(domain string) {\n\tif p.blockedBroadcaster == nil {\n\t\treturn\n\t}\n\tnormalized := strings.ToLower(strings.TrimSuffix(domain, \".\"))\n\tif normalized == \"\" {\n\t\treturn\n\t}\n\n\tp.blockedBroadcaster.Publish(events.BlockedEvent{\n\t\tHostname: normalized,\n\t\tTimestamp: time.Now().UTC(),\n\t})\n}\n\n// extractResolvedIPs parses A and AAAA records from resp.Answer into ResolvedIP slice.\n//\n// Uses netip.ParseAddr(v.A.String()) which allocates a temporary string per record; typically\n// one or a few records per resolution, so the cost is small compared to DNS RTT and nft writes.\nfunc extractResolvedIPs(resp *dns.Msg) []nftables.ResolvedIP {\n\tif resp == nil || len(resp.Answer) == 0 {\n\t\treturn nil\n\t}\n\n\tvar out []nftables.ResolvedIP\n\tfor _, rr := range resp.Answer {\n\t\tswitch v := rr.(type) {\n\t\tcase *dns.A:\n\t\t\tif v.A == nil {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\taddr, err := netip.ParseAddr(v.A.String())\n\t\t\tif err != nil {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tout = append(out, nftables.ResolvedIP{Addr: addr, TTL: time.Duration(v.Hdr.Ttl) * time.Second})\n\t\tcase *dns.AAAA:\n\t\t\tif v.AAAA == nil {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\taddr, err := netip.ParseAddr(v.AAAA.String())\n\t\t\tif err != nil {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tout = append(out, nftables.ResolvedIP{Addr: addr, TTL: time.Duration(v.Hdr.Ttl) * time.Second})\n\t\t}\n\t}\n\treturn out\n}\n\nconst fallbackUpstream = \"8.8.8.8:53\"\n\nfunc discoverUpstream() (string, error) {\n\tcfg, err := dns.ClientConfigFromFile(\"/etc/resolv.conf\")\n\tif err != nil || len(cfg.Servers) == 0 {\n\t\tif err != nil {\n\t\t\tlog.Warnf(\"[dns] fallback upstream resolver due to error: %v\", err)\n\t\t}\n\t\treturn fallbackUpstream, nil\n\t}\n\t// Prefer first non-loopback nameserver (e.g. K8s cluster DNS after 127.0.0.11).\n\t// If only loopback exists (e.g. Docker 127.0.0.11), use it: proxy upstream traffic\n\t// is marked and bypasses the redirect, so loopback is reachable from the sidecar.\n\tvar chosen string\n\tfor _, s := range cfg.Servers {\n\t\tif ip := net.ParseIP(s); ip != nil && ip.IsLoopback() {\n\t\t\tif chosen == \"\" {\n\t\t\t\tchosen = s\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tchosen = s\n\t\tbreak\n\t}\n\tif chosen == \"\" {\n\t\tchosen = cfg.Servers[0]\n\t}\n\treturn net.JoinHostPort(chosen, cfg.Port), nil\n}\n\n// ResolvNameserverIPs reads nameserver lines from resolvPath and returns parsed IPv4/IPv6 addresses.\n// Used at startup to whitelist the system DNS so client traffic to it is allowed and proxy can use it as upstream.\nfunc ResolvNameserverIPs(resolvPath string) ([]netip.Addr, error) {\n\tcfg, err := dns.ClientConfigFromFile(resolvPath)\n\tif err != nil || len(cfg.Servers) == 0 {\n\t\treturn nil, nil\n\t}\n\tvar out []netip.Addr\n\tfor _, s := range cfg.Servers {\n\t\tip, err := netip.ParseAddr(s)\n\t\tif err != nil {\n\t\t\tcontinue\n\t\t}\n\t\tout = append(out, ip)\n\t}\n\treturn out, nil\n}\n\n// LoadPolicyFromEnvVar reads the given env var and parses a policy; empty falls back to default deny-all.\nfunc LoadPolicyFromEnvVar(envName string) (*policy.NetworkPolicy, error) {\n\traw := os.Getenv(envName)\n\tif raw == \"\" {\n\t\treturn policy.DefaultDenyPolicy(), nil\n\t}\n\treturn policy.ParsePolicy(raw)\n}\n\nfunc ensurePolicyDefaults(p *policy.NetworkPolicy) *policy.NetworkPolicy {\n\tif p == nil {\n\t\treturn policy.DefaultDenyPolicy()\n\t}\n\tif p.DefaultAction == \"\" {\n\t\tp.DefaultAction = policy.ActionDeny\n\t}\n\treturn p\n}\n" }, { "path": "components/egress/pkg/dnsproxy/proxy_linux.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build linux\n\npackage dnsproxy\n\nimport (\n\t\"net\"\n\t\"sync\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"golang.org/x/sys/unix\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n)\n\nvar exemptDialerLogOnce sync.Once\n\n// dialerWithMark sets SO_MARK so iptables can RETURN marked packets (bypass\n// redirect for proxy's own upstream DNS queries). When upstream is in the nameserver\n// exempt list, returns a plain dialer (no mark) so upstream traffic follows normal\n// routing (e.g. via tun); iptables still does not redirect by destination exempt.\nfunc (p *Proxy) dialerWithMark() *net.Dialer {\n\tif UpstreamInExemptList(p.UpstreamHost()) {\n\t\texemptDialerLogOnce.Do(func() {\n\t\t\tlog.Infof(\"[dns] upstream %s in nameserver exempt list, not setting SO_MARK\", p.UpstreamHost())\n\t\t})\n\t\treturn &net.Dialer{Timeout: 5 * time.Second}\n\t}\n\n\treturn &net.Dialer{\n\t\tTimeout: 5 * time.Second,\n\t\tControl: func(network, address string, c syscall.RawConn) error {\n\t\t\tvar opErr error\n\t\t\tif err := c.Control(func(fd uintptr) {\n\t\t\t\topErr = unix.SetsockoptInt(int(fd), unix.SOL_SOCKET, unix.SO_MARK, constants.MarkValue)\n\t\t\t}); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\treturn opErr\n\t\t},\n\t}\n}\n" }, { "path": "components/egress/pkg/dnsproxy/proxy_other.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build !linux\n\npackage dnsproxy\n\nimport (\n\t\"net\"\n\t\"time\"\n)\n\n// Non-linux: no SO_MARK; return basic dialer.\nfunc (p *Proxy) dialerWithMark() *net.Dialer {\n\treturn &net.Dialer{Timeout: 5 * time.Second}\n}\n" }, { "path": "components/egress/pkg/dnsproxy/proxy_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage dnsproxy\n\nimport (\n\t\"net\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/miekg/dns\"\n\t\"github.com/stretchr/testify/require\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/nftables\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/policy\"\n)\n\nfunc TestProxyUpdatePolicy(t *testing.T) {\n\tproxy, err := New(nil, \"127.0.0.1:15353\")\n\trequire.NoError(t, err, \"init proxy\")\n\n\trequire.NotNil(t, proxy.CurrentPolicy(), \"expected default deny policy (non-nil)\")\n\trequire.Equal(t, policy.ActionDeny, proxy.CurrentPolicy().Evaluate(\"example.com.\"), \"expected default deny\")\n\n\tpol, err := policy.ParsePolicy(`{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"example.com\"}]}`)\n\trequire.NoError(t, err, \"parse policy\")\n\n\tproxy.UpdatePolicy(pol)\n\trequire.NotNil(t, proxy.CurrentPolicy(), \"expected policy after update\")\n\trequire.Equal(t, policy.ActionAllow, proxy.CurrentPolicy().Evaluate(\"example.com.\"), \"policy evaluation mismatch\")\n\n\tproxy.UpdatePolicy(nil)\n\trequire.NotNil(t, proxy.CurrentPolicy(), \"expected default deny policy after clearing\")\n\trequire.Equal(t, policy.ActionDeny, proxy.CurrentPolicy().Evaluate(\"example.com.\"), \"expected default deny after clearing\")\n}\n\nfunc TestLoadPolicyFromEnvVar(t *testing.T) {\n\tconst envName = \"TEST_EGRESS_POLICY\"\n\tt.Setenv(envName, `{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"example.com\"}]}`)\n\n\tpol, err := LoadPolicyFromEnvVar(envName)\n\trequire.NoError(t, err, \"unexpected error\")\n\trequire.NotNil(t, pol, \"expected parsed policy\")\n\trequire.Equal(t, policy.ActionAllow, pol.Evaluate(\"example.com.\"), \"expected parsed policy to allow example.com\")\n\n\tt.Setenv(envName, \"\")\n\tpol, err = LoadPolicyFromEnvVar(envName)\n\trequire.NoError(t, err, \"unexpected error on empty env\")\n\trequire.NotNil(t, pol, \"expected default deny policy when env is empty\")\n\trequire.Equal(t, policy.ActionDeny, pol.DefaultAction, \"expected default deny when env is empty\")\n}\n\nfunc TestExtractResolvedIPs(t *testing.T) {\n\tmsg := new(dns.Msg)\n\tmsg.Answer = []dns.RR{\n\t\t&dns.A{Hdr: dns.RR_Header{Name: \"example.com.\", Ttl: 120}, A: net.ParseIP(\"1.2.3.4\")},\n\t\t&dns.AAAA{Hdr: dns.RR_Header{Name: \"example.com.\", Ttl: 60}, AAAA: net.ParseIP(\"2001:db8::1\")},\n\t\t&dns.A{Hdr: dns.RR_Header{Name: \"example.com.\", Ttl: 90}, A: net.ParseIP(\"5.6.7.8\")},\n\t}\n\tips := extractResolvedIPs(msg)\n\trequire.Len(t, ips, 3, \"expected 3 IPs\")\n\t// Order follows Answer; check first A and AAAA\n\trequire.Equal(t, \"1.2.3.4\", ips[0].Addr.String(), \"first IP mismatch\")\n\trequire.Equal(t, 120*time.Second, ips[0].TTL, \"first IP TTL mismatch\")\n\trequire.Equal(t, \"2001:db8::1\", ips[1].Addr.String(), \"second IP mismatch\")\n\trequire.Equal(t, 60*time.Second, ips[1].TTL, \"second IP TTL mismatch\")\n\trequire.Equal(t, \"5.6.7.8\", ips[2].Addr.String(), \"third IP mismatch\")\n\trequire.Equal(t, 90*time.Second, ips[2].TTL, \"third IP TTL mismatch\")\n}\n\nfunc TestExtractResolvedIPs_EmptyOrNil(t *testing.T) {\n\trequire.Nil(t, extractResolvedIPs(nil), \"nil msg: expected nil\")\n\tmsg := new(dns.Msg)\n\trequire.Nil(t, extractResolvedIPs(msg), \"empty answer: expected nil\")\n\tmsg.Answer = []dns.RR{&dns.CNAME{Hdr: dns.RR_Header{Name: \"x.\"}, Target: \"y.\"}}\n\trequire.Nil(t, extractResolvedIPs(msg), \"CNAME only: expected nil\")\n}\n\nfunc TestSetOnResolved(t *testing.T) {\n\tproxy, err := New(policy.DefaultDenyPolicy(), \"\")\n\trequire.NoError(t, err)\n\tvar called bool\n\tvar capturedDomain string\n\tvar capturedIPs []nftables.ResolvedIP\n\tproxy.SetOnResolved(func(domain string, ips []nftables.ResolvedIP) {\n\t\tcalled = true\n\t\tcapturedDomain = domain\n\t\tcapturedIPs = ips\n\t})\n\trequire.NotNil(t, proxy.onResolved, \"SetOnResolved did not set callback\")\n\tproxy.SetOnResolved(nil)\n\trequire.Nil(t, proxy.onResolved, \"SetOnResolved(nil) did not clear callback\")\n\t_ = called\n\t_ = capturedDomain\n\t_ = capturedIPs\n}\n\nfunc TestMaybeNotifyResolved_CallsCallbackWhenAOrAAAA(t *testing.T) {\n\tproxy, err := New(policy.DefaultDenyPolicy(), \"\")\n\trequire.NoError(t, err)\n\tch := make(chan struct {\n\t\tdomain string\n\t\tips []nftables.ResolvedIP\n\t}, 1)\n\tproxy.SetOnResolved(func(domain string, ips []nftables.ResolvedIP) {\n\t\tch <- struct {\n\t\t\tdomain string\n\t\t\tips []nftables.ResolvedIP\n\t\t}{domain, ips}\n\t})\n\n\tmsg := new(dns.Msg)\n\tmsg.Answer = []dns.RR{\n\t\t&dns.A{Hdr: dns.RR_Header{Name: \"example.com.\", Ttl: 120}, A: net.ParseIP(\"1.2.3.4\")},\n\t}\n\tproxy.maybeNotifyResolved(\"example.com.\", msg)\n\n\tselect {\n\tcase got := <-ch:\n\t\trequire.Equal(t, \"example.com.\", got.domain, \"domain mismatch\")\n\t\trequire.Len(t, got.ips, 1, \"expected one resolved IP\")\n\t\trequire.Equal(t, \"1.2.3.4\", got.ips[0].Addr.String(), \"resolved IP mismatch\")\n\tcase <-time.After(2 * time.Second):\n\t\trequire.FailNow(t, \"callback was not invoked\")\n\t}\n}\n\nfunc TestMaybeNotifyResolved_NoCallWhenOnResolvedNil(t *testing.T) {\n\tproxy, err := New(policy.DefaultDenyPolicy(), \"\")\n\trequire.NoError(t, err)\n\tmsg := new(dns.Msg)\n\tmsg.Answer = []dns.RR{&dns.A{Hdr: dns.RR_Header{Name: \"x.\", Ttl: 60}, A: net.ParseIP(\"10.0.0.1\")}}\n\tproxy.maybeNotifyResolved(\"x.\", msg)\n\t// No callback set; should not panic. No assertion needed.\n}\n\nfunc TestMaybeNotifyResolved_NoCallWhenNoAOrAAAA(t *testing.T) {\n\tproxy, err := New(policy.DefaultDenyPolicy(), \"\")\n\trequire.NoError(t, err)\n\tch := make(chan struct {\n\t\tdomain string\n\t\tips []nftables.ResolvedIP\n\t}, 1)\n\tproxy.SetOnResolved(func(domain string, ips []nftables.ResolvedIP) {\n\t\tch <- struct {\n\t\t\tdomain string\n\t\t\tips []nftables.ResolvedIP\n\t\t}{domain, ips}\n\t})\n\n\tmsg := new(dns.Msg)\n\tmsg.Answer = []dns.RR{&dns.CNAME{Hdr: dns.RR_Header{Name: \"x.\"}, Target: \"y.\"}}\n\tproxy.maybeNotifyResolved(\"x.\", msg)\n\n\tselect {\n\tcase <-ch:\n\t\trequire.FailNow(t, \"callback should not be invoked when resp has no A/AAAA\")\n\tcase <-time.After(200 * time.Millisecond):\n\t\t// Expected: no callback\n\t}\n}\n" }, { "path": "components/egress/pkg/events/broadcaster.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage events\n\nimport (\n\t\"context\"\n\t\"sync\"\n\t\"sync/atomic\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n)\n\nconst defaultQueueSize = 128\n\n// BlockedEvent describes a blocked hostname notification.\ntype BlockedEvent struct {\n\tHostname string `json:\"hostname\"`\n\tTimestamp time.Time `json:\"timestamp\"`\n}\n\n// Subscriber consumes blocked events.\ntype Subscriber interface {\n\tHandleBlocked(ctx context.Context, ev BlockedEvent)\n}\n\n// BroadcasterConfig defines queue sizing for the broadcaster.\ntype BroadcasterConfig struct {\n\tQueueSize int\n}\n\n// Broadcaster fans out blocked events to one or more subscribers via channels.\ntype Broadcaster struct {\n\tctx context.Context\n\tcancel context.CancelFunc\n\n\tmu sync.RWMutex\n\tsubscribers []chan BlockedEvent\n\tqueueSize int\n\tclosed atomic.Bool\n}\n\n// NewBroadcaster builds a broadcaster with the given queue size (defaults to 128).\nfunc NewBroadcaster(ctx context.Context, cfg BroadcasterConfig) *Broadcaster {\n\tif cfg.QueueSize <= 0 {\n\t\tcfg.QueueSize = defaultQueueSize\n\t}\n\tcctx, cancel := context.WithCancel(ctx)\n\treturn &Broadcaster{\n\t\tctx: cctx,\n\t\tcancel: cancel,\n\t\tqueueSize: cfg.QueueSize,\n\t}\n}\n\n// AddSubscriber registers a new subscriber with its own buffered queue and worker.\nfunc (b *Broadcaster) AddSubscriber(sub Subscriber) {\n\tif sub == nil {\n\t\treturn\n\t}\n\tch := make(chan BlockedEvent, b.queueSize)\n\n\tb.mu.Lock()\n\tb.subscribers = append(b.subscribers, ch)\n\tb.mu.Unlock()\n\n\tgo func() {\n\t\tfor {\n\t\t\tselect {\n\t\t\tcase <-b.ctx.Done():\n\t\t\t\treturn\n\t\t\tcase ev, ok := <-ch:\n\t\t\t\tif !ok {\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\tsub.HandleBlocked(b.ctx, ev)\n\t\t\t}\n\t\t}\n\t}()\n}\n\n// Publish sends an event to all subscribers; drops and logs when a subscriber queue is full.\nfunc (b *Broadcaster) Publish(event BlockedEvent) {\n\tif b.closed.Load() {\n\t\treturn\n\t}\n\n\tb.mu.RLock()\n\tdefer b.mu.RUnlock()\n\n\tfor _, ch := range b.subscribers {\n\t\tselect {\n\t\tcase ch <- event:\n\t\tdefault:\n\t\t\tlog.Warnf(\"[events] blocked-event queue full; dropping hostname %s\", event.Hostname)\n\t\t}\n\t}\n}\n\n// Close stops all workers and closes subscriber queues.\nfunc (b *Broadcaster) Close() {\n\tif b.closed.Load() {\n\t\treturn\n\t}\n\n\tb.cancel()\n\n\tb.mu.Lock()\n\tdefer b.mu.Unlock()\n\tsubs := b.subscribers\n\tb.subscribers = nil\n\n\tfor _, ch := range subs {\n\t\tclose(ch)\n\t}\n\tb.closed.Store(true)\n}\n" }, { "path": "components/egress/pkg/events/events_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage events\n\nimport (\n\t\"context\"\n\t\"encoding/json\"\n\t\"io\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/stretchr/testify/require\"\n)\n\ntype captureSubscriber struct {\n\trecv chan BlockedEvent\n}\n\nfunc (c *captureSubscriber) HandleBlocked(_ context.Context, ev BlockedEvent) {\n\tc.recv <- ev\n}\n\ntype blockingSubscriber struct {\n\tblock chan struct{}\n}\n\nfunc (b *blockingSubscriber) HandleBlocked(_ context.Context, ev BlockedEvent) {\n\t// Block until the channel is closed to simulate a slow consumer and trigger backpressure.\n\t<-b.block\n\t_ = ev\n}\n\nfunc TestBroadcasterFanout(t *testing.T) {\n\tctx, cancel := context.WithCancel(context.Background())\n\tdefer cancel()\n\n\tb := NewBroadcaster(ctx, BroadcasterConfig{QueueSize: 2})\n\n\tsub1 := &captureSubscriber{recv: make(chan BlockedEvent, 1)}\n\tsub2 := &captureSubscriber{recv: make(chan BlockedEvent, 1)}\n\tb.AddSubscriber(sub1)\n\tb.AddSubscriber(sub2)\n\n\tev := BlockedEvent{Hostname: \"example.com.\", Timestamp: time.Now()}\n\tb.Publish(ev)\n\n\tselect {\n\tcase got := <-sub1.recv:\n\t\trequire.Equal(t, ev.Hostname, got.Hostname, \"sub1 expected hostname\")\n\tcase <-time.After(2 * time.Second):\n\t\trequire.FailNow(t, \"sub1 did not receive event\")\n\t}\n\n\tselect {\n\tcase got := <-sub2.recv:\n\t\trequire.Equal(t, ev.Hostname, got.Hostname, \"sub2 expected hostname\")\n\tcase <-time.After(2 * time.Second):\n\t\trequire.FailNow(t, \"sub2 did not receive event\")\n\t}\n\n\tb.Close()\n}\n\nfunc TestBroadcasterDropsWhenSubscriberBackedUp(t *testing.T) {\n\tctx, cancel := context.WithCancel(context.Background())\n\tdefer cancel()\n\n\t// Small queue; blocking subscriber will hold the first event.\n\tb := NewBroadcaster(ctx, BroadcasterConfig{QueueSize: 1})\n\tblock := make(chan struct{})\n\tsub := &blockingSubscriber{block: block}\n\tb.AddSubscriber(sub)\n\n\tev1 := BlockedEvent{Hostname: \"first.example\", Timestamp: time.Now()}\n\tev2 := BlockedEvent{Hostname: \"second.example\", Timestamp: time.Now()}\n\n\tb.Publish(ev1)\n\t// This publish should drop because subscriber is blocked and queue size is 1.\n\tb.Publish(ev2)\n\n\t// Allow subscriber to drain and exit.\n\tclose(block)\n\n\tb.Close()\n}\n\nfunc TestWebhookSubscriberSendsPayload(t *testing.T) {\n\tvar (\n\t\tgotMethod string\n\t\tgotPayload webhookPayload\n\t)\n\tconst (\n\t\tsandboxIDInitial = \"sandbox-test\"\n\t\tsandboxIDLater = \"sandbox-updated\"\n\t)\n\tt.Setenv(constants.ENVSandboxID, sandboxIDInitial)\n\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\tgotMethod = r.Method\n\t\tbody, _ := io.ReadAll(r.Body)\n\t\t_ = r.Body.Close()\n\t\t_ = json.Unmarshal(body, &gotPayload)\n\t\tw.WriteHeader(http.StatusOK)\n\t}))\n\tdefer server.Close()\n\n\tsub := NewWebhookSubscriber(server.URL)\n\trequire.NotNil(t, sub, \"webhook subscriber should not be nil\")\n\tt.Setenv(constants.ENVSandboxID, sandboxIDLater)\n\n\tts := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)\n\tev := BlockedEvent{Hostname: \"Example.com.\", Timestamp: ts}\n\tsub.HandleBlocked(context.Background(), ev)\n\n\trequire.Equal(t, http.MethodPost, gotMethod, \"expected POST\")\n\trequire.Equal(t, ev.Hostname, gotPayload.Hostname, \"expected hostname\")\n\trequire.Equal(t, webhookSource, gotPayload.Source, \"expected source\")\n\trequire.Equal(t, sandboxIDInitial, gotPayload.SandboxID, \"expected sandboxId captured at init\")\n\trequire.NotEmpty(t, gotPayload.Timestamp, \"expected timestamp to be set\")\n}\n" }, { "path": "components/egress/pkg/events/webhook.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage events\n\nimport (\n\t\"bytes\"\n\t\"context\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n)\n\nconst (\n\twebhookSource = \"opensandbox-egress\"\n\tdefaultWebhookTimeout = 5 * time.Second\n\tdefaultWebhookRetries = 3\n\tdefaultWebhookBackoff = 1 * time.Second\n)\n\n// WebhookSubscriber delivers blocked events to an HTTP endpoint.\ntype WebhookSubscriber struct {\n\turl string\n\tclient *http.Client\n\ttimeout time.Duration\n\tmaxRetries int\n\tbackoff time.Duration\n\tsandboxID string\n}\n\ntype webhookPayload struct {\n\tHostname string `json:\"hostname\"`\n\tTimestamp string `json:\"timestamp\"`\n\tSource string `json:\"source\"`\n\tSandboxID string `json:\"sandboxId\"`\n}\n\n// NewWebhookSubscriber builds a webhook subscriber with hardcoded timeout/retry settings.\nfunc NewWebhookSubscriber(url string) *WebhookSubscriber {\n\tif url == \"\" {\n\t\treturn nil\n\t}\n\treturn &WebhookSubscriber{\n\t\turl: url,\n\t\tclient: &http.Client{},\n\t\ttimeout: defaultWebhookTimeout,\n\t\tmaxRetries: defaultWebhookRetries,\n\t\tbackoff: defaultWebhookBackoff,\n\t\tsandboxID: os.Getenv(constants.ENVSandboxID),\n\t}\n}\n\n// HandleBlocked sends the blocked event to the configured webhook with retries.\nfunc (w *WebhookSubscriber) HandleBlocked(ctx context.Context, ev BlockedEvent) {\n\tpayload := webhookPayload{\n\t\tHostname: ev.Hostname,\n\t\tTimestamp: ev.Timestamp.UTC().Format(time.RFC3339),\n\t\tSource: webhookSource,\n\t\tSandboxID: w.sandboxID,\n\t}\n\tbody, err := json.Marshal(payload)\n\tif err != nil {\n\t\tlog.Warnf(\"[webhook] failed to marshal payload for hostname %s: %v\", ev.Hostname, err)\n\t\treturn\n\t}\n\n\tvar lastErr error\n\tfor attempt := 0; attempt <= w.maxRetries; attempt++ {\n\t\treqCtx := ctx\n\t\tcancel := func() {}\n\t\tif w.timeout > 0 {\n\t\t\treqCtx, cancel = context.WithTimeout(ctx, w.timeout)\n\t\t}\n\n\t\treq, err := http.NewRequestWithContext(reqCtx, http.MethodPost, w.url, bytes.NewReader(body))\n\t\tif err != nil {\n\t\t\tcancel()\n\t\t\tlastErr = err\n\t\t\tbreak\n\t\t}\n\t\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t\tresp, err := w.client.Do(req)\n\t\tif err == nil {\n\t\t\t_, _ = io.Copy(io.Discard, resp.Body)\n\t\t\t_ = resp.Body.Close()\n\t\t\tif resp.StatusCode < 300 {\n\t\t\t\tcancel()\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif resp.StatusCode < 500 {\n\t\t\t\tcancel()\n\t\t\t\tlog.Warnf(\"[webhook] non-retriable status %d for hostname %s\", resp.StatusCode, payload.Hostname)\n\t\t\t\treturn\n\t\t\t}\n\t\t\terr = fmt.Errorf(\"status %d\", resp.StatusCode)\n\t\t}\n\n\t\tcancel()\n\t\tlastErr = err\n\t\tif attempt < w.maxRetries {\n\t\t\ttime.Sleep(w.backoff * time.Duration(1< port).\n//\n// exemptDst: optional list of destination IPs; traffic to these is not redirected. Packets carrying mark are also RETURNed (proxy's own upstream). Requires CAP_NET_ADMIN.\nfunc SetupRedirect(port int, exemptDst []netip.Addr) error {\n\tlog.Infof(\"installing iptables DNS redirect: OUTPUT port 53 -> %d (mark %s bypass)\", port, constants.MarkHex)\n\ttargetPort := strconv.Itoa(port)\n\n\tvar rules [][]string\n\tfor _, d := range exemptDst {\n\t\taddr := d\n\t\tdStr := d.String()\n\t\tif addr.Is4() {\n\t\t\trules = append(rules,\n\t\t\t\t[]string{\"iptables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"udp\", \"--dport\", \"53\", \"-d\", dStr, \"-j\", \"RETURN\"},\n\t\t\t\t[]string{\"iptables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"tcp\", \"--dport\", \"53\", \"-d\", dStr, \"-j\", \"RETURN\"},\n\t\t\t)\n\t\t} else {\n\t\t\trules = append(rules,\n\t\t\t\t[]string{\"ip6tables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"udp\", \"--dport\", \"53\", \"-d\", dStr, \"-j\", \"RETURN\"},\n\t\t\t\t[]string{\"ip6tables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"tcp\", \"--dport\", \"53\", \"-d\", dStr, \"-j\", \"RETURN\"},\n\t\t\t)\n\t\t}\n\t}\n\t// Bypass packets marked by the proxy itself (see dnsproxy dialer).\n\tmarkAndRedirect := [][]string{\n\t\t{\"iptables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"udp\", \"--dport\", \"53\", \"-m\", \"mark\", \"--mark\", constants.MarkHex, \"-j\", \"RETURN\"},\n\t\t{\"iptables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"tcp\", \"--dport\", \"53\", \"-m\", \"mark\", \"--mark\", constants.MarkHex, \"-j\", \"RETURN\"},\n\t\t// Redirect all other DNS traffic to local proxy port.\n\t\t{\"iptables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"udp\", \"--dport\", \"53\", \"-j\", \"REDIRECT\", \"--to-port\", targetPort},\n\t\t{\"iptables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"tcp\", \"--dport\", \"53\", \"-j\", \"REDIRECT\", \"--to-port\", targetPort},\n\t\t// IPv6 equivalents (ip6tables)\n\t\t{\"ip6tables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"udp\", \"--dport\", \"53\", \"-m\", \"mark\", \"--mark\", constants.MarkHex, \"-j\", \"RETURN\"},\n\t\t{\"ip6tables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"tcp\", \"--dport\", \"53\", \"-m\", \"mark\", \"--mark\", constants.MarkHex, \"-j\", \"RETURN\"},\n\t\t{\"ip6tables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"udp\", \"--dport\", \"53\", \"-j\", \"REDIRECT\", \"--to-port\", targetPort},\n\t\t{\"ip6tables\", \"-t\", \"nat\", \"-A\", \"OUTPUT\", \"-p\", \"tcp\", \"--dport\", \"53\", \"-j\", \"REDIRECT\", \"--to-port\", targetPort},\n\t}\n\trules = append(rules, markAndRedirect...)\n\n\tfor _, args := range rules {\n\t\tif output, err := exec.Command(args[0], args[1:]...).CombinedOutput(); err != nil {\n\t\t\treturn fmt.Errorf(\"iptables command failed: %v (output: %s)\", err, output)\n\t\t}\n\t}\n\tlog.Infof(\"iptables DNS redirect installed successfully\")\n\treturn nil\n}\n" }, { "path": "components/egress/pkg/log/logger.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage log\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n)\n\n// Logger is the shared logger instance for egress.\nvar Logger slogger.Logger = slogger.MustNew(slogger.Config{Level: \"info\"}).Named(\"opensandbox.egress\")\n\n// WithLogger replaces the global logger used by egress components.\nfunc WithLogger(ctx context.Context, logger slogger.Logger) context.Context {\n\tif logger != nil {\n\t\tLogger = logger\n\t}\n\treturn ctx\n}\n\nfunc Debugf(template string, args ...any) {\n\tLogger.Debugf(template, args...)\n}\n\nfunc Infof(template string, args ...any) {\n\tLogger.Infof(template, args...)\n}\n\nfunc Warnf(template string, args ...any) {\n\tLogger.Warnf(template, args...)\n}\n\nfunc Errorf(template string, args ...any) {\n\tLogger.Errorf(template, args...)\n}\n\nfunc Fatalf(template string, args ...any) {\n\tLogger.Errorf(template, args...)\n\t_ = Logger.Sync()\n\tos.Exit(1)\n}\n" }, { "path": "components/egress/pkg/nftables/dynamic.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage nftables\n\nimport (\n\t\"fmt\"\n\t\"net/netip\"\n\t\"strings\"\n\t\"time\"\n)\n\nconst (\n\tdynAllowV4Set = \"dyn_allow_v4\"\n\tdynAllowV6Set = \"dyn_allow_v6\"\n\tdynSetTimeoutS = 300\n\tminTTLSec = 60\n\tmaxTTLSec = 300\n)\n\n// ResolvedIP is a single IP learned from DNS with TTL for dynamic nft set.\ntype ResolvedIP struct {\n\tAddr netip.Addr\n\tTTL time.Duration\n}\n\n// buildAddResolvedIPsScript returns a nft script fragment that\n// adds resolved IPs to dyn_allow_v4/v6 with timeout.\nfunc buildAddResolvedIPsScript(table string, ips []ResolvedIP) string {\n\tvar v4, v6 []string\n\tfor _, r := range ips {\n\t\tsec := clampTTL(r.TTL)\n\t\tif r.Addr.Is4() {\n\t\t\tv4 = append(v4, fmt.Sprintf(\"%s timeout %ds\", r.Addr.String(), sec))\n\t\t} else if r.Addr.Is6() {\n\t\t\tv6 = append(v6, fmt.Sprintf(\"%s timeout %ds\", r.Addr.String(), sec))\n\t\t}\n\t}\n\tvar b strings.Builder\n\tif len(v4) > 0 {\n\t\tfmt.Fprintf(&b, \"add element inet %s %s { %s }\\n\", table, dynAllowV4Set, strings.Join(v4, \", \"))\n\t}\n\tif len(v6) > 0 {\n\t\tfmt.Fprintf(&b, \"add element inet %s %s { %s }\\n\", table, dynAllowV6Set, strings.Join(v6, \", \"))\n\t}\n\treturn b.String()\n}\n\nfunc clampTTL(d time.Duration) int {\n\tsec := int(d.Seconds())\n\tif sec < minTTLSec {\n\t\treturn minTTLSec\n\t}\n\tif sec > maxTTLSec {\n\t\treturn maxTTLSec\n\t}\n\treturn sec\n}\n" }, { "path": "components/egress/pkg/nftables/manager.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage nftables\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"os/exec\"\n\t\"strings\"\n\t\"sync\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/policy\"\n)\n\nconst (\n\ttableName = \"opensandbox\"\n\tchainName = \"egress\"\n\tallowV4Set = \"allow_v4\"\n\tallowV6Set = \"allow_v6\"\n\tdenyV4Set = \"deny_v4\"\n\tdenyV6Set = \"deny_v6\"\n\tdohBlockV4Set = \"doh_block_v4\"\n\tdohBlockV6Set = \"doh_block_v6\"\n)\n\ntype runner func(ctx context.Context, script string) ([]byte, error)\n\n// Options controls nftables enforcement extras.\ntype Options struct {\n\t// BlockDoT drops tcp/udp 853 to prevent DNS-over-TLS bypass.\n\tBlockDoT bool\n\t// BlockDoH443 drops HTTPS DoH endpoints; when blocklist is empty and enabled, 443 is dropped.\n\tBlockDoH443 bool\n\tDoHBlocklistV4 []string\n\tDoHBlocklistV6 []string\n}\n\n// Manager applies static IP/CIDR policy into nftables and dynamic DNS-learned IPs.\ntype Manager struct {\n\trun runner\n\topts Options\n\tmu sync.Mutex\n}\n\n// NewManager builds an nftables manager that shells out to `nft -f -` with defaults.\nfunc NewManager() *Manager {\n\treturn &Manager{run: defaultRunner, opts: Options{BlockDoT: true}}\n}\n\n// NewManagerWithRunner is for tests; allows capturing the rendered ruleset (defaults to BlockDoT=true).\nfunc NewManagerWithRunner(r runner) *Manager {\n\treturn &Manager{run: r, opts: Options{BlockDoT: true}}\n}\n\n// NewManagerWithRunnerAndOptions is for tests needing custom options.\nfunc NewManagerWithRunnerAndOptions(r runner, opts Options) *Manager {\n\treturn &Manager{run: r, opts: opts}\n}\n\n// NewManagerWithOptions allows customizing behavior (used by main()).\nfunc NewManagerWithOptions(opts Options) *Manager {\n\treturn &Manager{run: defaultRunner, opts: opts}\n}\n\n// ApplyStatic reconciles static allow/deny IP and CIDR entries into nftables.\n//\n// It creates a dedicated table/chain and overwrites previous state.\n// Uses the same mutex as AddResolvedIPs so a /policy update never overlaps a DNS\n// callback: without this, add-element could run while the table is being deleted/recreated\n// and fail, causing a transient deny for a client that already got an allowed DNS answer.\nfunc (m *Manager) ApplyStatic(ctx context.Context, p *policy.NetworkPolicy) error {\n\tif p == nil {\n\t\tp = policy.DefaultDenyPolicy()\n\t}\n\tallowV4, allowV6, denyV4, denyV6 := p.StaticIPSets()\n\tlog.Infof(\"nftables: applying static policy: default=%s, allow_v4=%d, allow_v6=%d, deny_v4=%d, deny_v6=%d\",\n\t\tp.DefaultAction, len(allowV4), len(allowV6), len(denyV4), len(denyV6))\n\tm.mu.Lock()\n\tdefer m.mu.Unlock()\n\tscript := buildRuleset(p, m.opts)\n\tif _, err := m.run(ctx, script); err != nil {\n\t\t// On a fresh host the delete-table may fail; retry once without the delete line.\n\t\tif isMissingTableError(err) {\n\t\t\tfallback := removeDeleteTableLine(script)\n\t\t\tif fallback != script {\n\t\t\t\tif _, retryErr := m.run(ctx, fallback); retryErr == nil {\n\t\t\t\t\treturn nil\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn err\n\t}\n\tlog.Infof(\"nftables: static policy applied successfully\")\n\treturn nil\n}\n\n// AddResolvedIPs adds DNS-learned IPs to dynamic allow sets with TTL-based timeout.\n// TTL is clamped to minTTLSecโ€“maxTTLSec. Call only when table exists (dns+nft mode).\nfunc (m *Manager) AddResolvedIPs(ctx context.Context, ips []ResolvedIP) error {\n\tif len(ips) == 0 {\n\t\treturn nil\n\t}\n\n\tm.mu.Lock()\n\tdefer m.mu.Unlock()\n\tscript := buildAddResolvedIPsScript(tableName, ips)\n\tif script == \"\" {\n\t\treturn nil\n\t}\n\tlog.Infof(\"nftables: adding %d resolved IP(s) to dynamic allow sets with script statement %s\", len(ips), script)\n\t_, err := m.run(ctx, script)\n\treturn err\n}\n\nfunc buildRuleset(p *policy.NetworkPolicy, opts Options) string {\n\tallowV4, allowV6, denyV4, denyV6 := p.StaticIPSets()\n\n\tvar b strings.Builder\n\t// Reset and re-create table, sets, and chain.\n\tfmt.Fprintf(&b, \"delete table inet %s\\n\", tableName)\n\tfmt.Fprintf(&b, \"add table inet %s\\n\", tableName)\n\n\tfmt.Fprintf(&b, \"add set inet %s %s { type ipv4_addr; flags interval; }\\n\", tableName, allowV4Set)\n\tfmt.Fprintf(&b, \"add set inet %s %s { type ipv4_addr; flags interval; }\\n\", tableName, denyV4Set)\n\tfmt.Fprintf(&b, \"add set inet %s %s { type ipv6_addr; flags interval; }\\n\", tableName, allowV6Set)\n\tfmt.Fprintf(&b, \"add set inet %s %s { type ipv6_addr; flags interval; }\\n\", tableName, denyV6Set)\n\tfmt.Fprintf(&b, \"add set inet %s %s { type ipv4_addr; timeout %ds; }\\n\", tableName, dynAllowV4Set, dynSetTimeoutS)\n\tfmt.Fprintf(&b, \"add set inet %s %s { type ipv6_addr; timeout %ds; }\\n\", tableName, dynAllowV6Set, dynSetTimeoutS)\n\n\tif len(opts.DoHBlocklistV4) > 0 {\n\t\tfmt.Fprintf(&b, \"add set inet %s %s { type ipv4_addr; flags interval; }\\n\", tableName, dohBlockV4Set)\n\t}\n\tif len(opts.DoHBlocklistV6) > 0 {\n\t\tfmt.Fprintf(&b, \"add set inet %s %s { type ipv6_addr; flags interval; }\\n\", tableName, dohBlockV6Set)\n\t}\n\n\twriteElements(&b, allowV4Set, allowV4)\n\twriteElements(&b, denyV4Set, denyV4)\n\twriteElements(&b, allowV6Set, allowV6)\n\twriteElements(&b, denyV6Set, denyV6)\n\twriteElements(&b, dohBlockV4Set, opts.DoHBlocklistV4)\n\twriteElements(&b, dohBlockV6Set, opts.DoHBlocklistV6)\n\n\tchainPolicy := \"drop\"\n\tif p.DefaultAction == policy.ActionAllow {\n\t\tchainPolicy = \"accept\"\n\t}\n\tfmt.Fprintf(&b, \"add chain inet %s %s { type filter hook output priority 0; policy %s; }\\n\", tableName, chainName, chainPolicy)\n\tfmt.Fprintf(&b, \"add rule inet %s %s ct state established,related accept\\n\", tableName, chainName)\n\tfmt.Fprintf(&b, \"add rule inet %s %s meta mark %s accept\\n\", tableName, chainName, constants.MarkHex)\n\tfmt.Fprintf(&b, \"add rule inet %s %s oifname \\\"lo\\\" accept\\n\", tableName, chainName)\n\tif opts.BlockDoT {\n\t\tfmt.Fprintf(&b, \"add rule inet %s %s tcp dport 853 drop\\n\", tableName, chainName)\n\t\tfmt.Fprintf(&b, \"add rule inet %s %s udp dport 853 drop\\n\", tableName, chainName)\n\t}\n\tif opts.BlockDoH443 {\n\t\tif len(opts.DoHBlocklistV4) == 0 && len(opts.DoHBlocklistV6) == 0 {\n\t\t\t// strict: drop all 443 when enabled but no blocklist provided\n\t\t\tfmt.Fprintf(&b, \"add rule inet %s %s tcp dport 443 drop\\n\", tableName, chainName)\n\t\t} else {\n\t\t\tif len(opts.DoHBlocklistV4) > 0 {\n\t\t\t\tfmt.Fprintf(&b, \"add rule inet %s %s ip daddr @%s tcp dport 443 drop\\n\", tableName, chainName, dohBlockV4Set)\n\t\t\t}\n\t\t\tif len(opts.DoHBlocklistV6) > 0 {\n\t\t\t\tfmt.Fprintf(&b, \"add rule inet %s %s ip6 daddr @%s tcp dport 443 drop\\n\", tableName, chainName, dohBlockV6Set)\n\t\t\t}\n\t\t}\n\t}\n\tfmt.Fprintf(&b, \"add rule inet %s %s ip daddr @%s drop\\n\", tableName, chainName, denyV4Set)\n\tfmt.Fprintf(&b, \"add rule inet %s %s ip6 daddr @%s drop\\n\", tableName, chainName, denyV6Set)\n\tfmt.Fprintf(&b, \"add rule inet %s %s ip daddr @%s accept\\n\", tableName, chainName, dynAllowV4Set)\n\tfmt.Fprintf(&b, \"add rule inet %s %s ip6 daddr @%s accept\\n\", tableName, chainName, dynAllowV6Set)\n\tfmt.Fprintf(&b, \"add rule inet %s %s ip daddr @%s accept\\n\", tableName, chainName, allowV4Set)\n\tfmt.Fprintf(&b, \"add rule inet %s %s ip6 daddr @%s accept\\n\", tableName, chainName, allowV6Set)\n\tif chainPolicy == \"drop\" {\n\t\tfmt.Fprintf(&b, \"add rule inet %s %s counter drop\\n\", tableName, chainName)\n\t}\n\n\treturn b.String()\n}\n\nfunc writeElements(b *strings.Builder, setName string, elems []string) {\n\tif len(elems) == 0 {\n\t\treturn\n\t}\n\tfmt.Fprintf(b, \"add element inet %s %s { %s }\\n\", tableName, setName, strings.Join(elems, \", \"))\n}\n\nfunc defaultRunner(ctx context.Context, script string) ([]byte, error) {\n\tcmd := exec.CommandContext(ctx, \"nft\", \"-f\", \"-\")\n\tcmd.Stdin = strings.NewReader(script)\n\toutput, err := cmd.CombinedOutput()\n\tif err != nil {\n\t\treturn output, fmt.Errorf(\"nft apply failed: %w (output: %s)\", err, strings.TrimSpace(string(output)))\n\t}\n\treturn output, nil\n}\n\nfunc isMissingTableError(err error) bool {\n\tif err == nil {\n\t\treturn false\n\t}\n\tmsg := strings.ToLower(err.Error())\n\treturn strings.Contains(msg, \"no such file or directory\") && strings.Contains(msg, \"delete table inet \"+tableName)\n}\n\nfunc removeDeleteTableLine(script string) string {\n\tlines := strings.Split(script, \"\\n\")\n\tvar filtered []string\n\tfor _, l := range lines {\n\t\tif strings.HasPrefix(l, \"delete table inet \"+tableName) {\n\t\t\tcontinue\n\t\t}\n\t\tif strings.TrimSpace(l) == \"\" {\n\t\t\tcontinue\n\t\t}\n\t\tfiltered = append(filtered, l)\n\t}\n\treturn strings.Join(filtered, \"\\n\")\n}\n" }, { "path": "components/egress/pkg/nftables/manager_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage nftables\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"net/netip\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/policy\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestApplyStatic_BuildsRuleset_DefaultDeny(t *testing.T) {\n\tvar rendered string\n\tm := NewManagerWithRunner(func(_ context.Context, script string) ([]byte, error) {\n\t\trendered = script\n\t\treturn nil, nil\n\t})\n\n\tp, err := policy.ParsePolicy(`{\n\t\t\"defaultAction\":\"deny\",\n\t\t\"egress\":[\n\t\t\t{\"action\":\"allow\",\"target\":\"1.1.1.1\"},\n\t\t\t{\"action\":\"allow\",\"target\":\"2.2.0.0/16\"},\n\t\t\t{\"action\":\"deny\",\"target\":\"2001:db8::/32\"}\n\t\t]\n\t}`)\n\trequire.NoError(t, err, \"unexpected parse error\")\n\n\trequire.NoError(t, m.ApplyStatic(context.Background(), p), \"ApplyStatic returned error\")\n\n\texpectContains(t, rendered, \"add chain inet opensandbox egress { type filter hook output priority 0; policy drop; }\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress ct state established,related accept\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress meta mark 0x1 accept\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress oifname \\\"lo\\\" accept\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress tcp dport 853 drop\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress udp dport 853 drop\")\n\texpectContains(t, rendered, \"add set inet opensandbox dyn_allow_v4 { type ipv4_addr; timeout 300s; }\")\n\texpectContains(t, rendered, \"add set inet opensandbox dyn_allow_v6 { type ipv6_addr; timeout 300s; }\")\n\texpectContains(t, rendered, \"add element inet opensandbox allow_v4 { 1.1.1.1, 2.2.0.0/16 }\")\n\texpectContains(t, rendered, \"add element inet opensandbox deny_v6 { 2001:db8::/32 }\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress ip daddr @dyn_allow_v4 accept\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress ip6 daddr @dyn_allow_v6 accept\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress counter drop\")\n}\n\nfunc TestApplyStatic_DefaultAllowUsesAcceptPolicy(t *testing.T) {\n\tvar rendered string\n\tm := NewManagerWithRunner(func(_ context.Context, script string) ([]byte, error) {\n\t\trendered = script\n\t\treturn nil, nil\n\t})\n\n\tp, err := policy.ParsePolicy(`{\n\t\t\"defaultAction\":\"allow\",\n\t\t\"egress\":[{\"action\":\"deny\",\"target\":\"10.0.0.0/8\"}]\n\t}`)\n\trequire.NoError(t, err, \"unexpected parse error\")\n\n\trequire.NoError(t, m.ApplyStatic(context.Background(), p), \"ApplyStatic returned error\")\n\n\texpectContains(t, rendered, \"policy accept;\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress tcp dport 853 drop\")\n\trequire.NotContains(t, rendered, \"counter drop\", \"did not expect drop counter when defaultAction is allow:\\n%s\", rendered)\n\texpectContains(t, rendered, \"add element inet opensandbox deny_v4 { 10.0.0.0/8 }\")\n}\n\nfunc expectContains(t *testing.T, s, substr string) {\n\tt.Helper()\n\trequire.Contains(t, s, substr, \"expected rendered ruleset to contain %q\\nrendered:\\n%s\", substr, s)\n}\n\nfunc TestApplyStatic_RetryWhenTableMissing(t *testing.T) {\n\tvar calls int\n\tvar scripts []string\n\tm := NewManagerWithRunner(func(_ context.Context, script string) ([]byte, error) {\n\t\tcalls++\n\t\tscripts = append(scripts, script)\n\t\tif calls == 1 {\n\t\t\treturn nil, fmt.Errorf(\"nft apply failed: exit status 1 (output: /dev/stdin:1:19-29: Error: No such file or directory; did you mean table โ€˜opensandboxโ€™ in family inet?\\ndelete table inet opensandbox\\n ^^^^^^^^^^^)\")\n\t\t}\n\t\treturn nil, nil\n\t})\n\n\tp, _ := policy.ParsePolicy(`{\"egress\":[]}`)\n\trequire.NoError(t, m.ApplyStatic(context.Background(), p), \"expected retry to succeed\")\n\trequire.Equal(t, 2, calls, \"expected 2 calls (fail then retry)\")\n\trequire.GreaterOrEqual(t, len(scripts), 2, \"expected second attempt script to be recorded\")\n\trequire.NotContains(t, scripts[1], \"delete table inet opensandbox\", \"expected second attempt to drop delete-table line\")\n}\n\nfunc TestApplyStatic_DoHBlocklist(t *testing.T) {\n\tvar rendered string\n\topts := Options{\n\t\tBlockDoT: true,\n\t\tBlockDoH443: true,\n\t\tDoHBlocklistV4: []string{\"9.9.9.9\"},\n\t\tDoHBlocklistV6: []string{\"2001:db8::/32\"},\n\t}\n\tm := NewManagerWithRunnerAndOptions(func(_ context.Context, script string) ([]byte, error) {\n\t\trendered = script\n\t\treturn nil, nil\n\t}, opts)\n\n\tp, _ := policy.ParsePolicy(`{\"defaultAction\":\"allow\",\"egress\":[]}`)\n\trequire.NoError(t, m.ApplyStatic(context.Background(), p), \"ApplyStatic returned error\")\n\n\texpectContains(t, rendered, \"add set inet opensandbox doh_block_v4 { type ipv4_addr; flags interval; }\")\n\texpectContains(t, rendered, \"add element inet opensandbox doh_block_v4 { 9.9.9.9 }\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress ip daddr @doh_block_v4 tcp dport 443 drop\")\n\texpectContains(t, rendered, \"add rule inet opensandbox egress ip6 daddr @doh_block_v6 tcp dport 443 drop\")\n}\n\nfunc TestAddResolvedIPs_BuildsDynamicElements(t *testing.T) {\n\tvar rendered string\n\tm := NewManagerWithRunner(func(_ context.Context, script string) ([]byte, error) {\n\t\trendered = script\n\t\treturn nil, nil\n\t})\n\tips := []ResolvedIP{\n\t\t{Addr: netip.MustParseAddr(\"1.1.1.1\"), TTL: 120 * time.Second},\n\t\t{Addr: netip.MustParseAddr(\"2001:db8::1\"), TTL: 60 * time.Second},\n\t}\n\trequire.NoError(t, m.AddResolvedIPs(context.Background(), ips), \"AddResolvedIPs returned error\")\n\texpectContains(t, rendered, \"add element inet opensandbox dyn_allow_v4 { 1.1.1.1 timeout 120s }\")\n\texpectContains(t, rendered, \"add element inet opensandbox dyn_allow_v6 { 2001:db8::1 timeout 60s }\")\n}\n\nfunc TestAddResolvedIPs_ClampsTTL(t *testing.T) {\n\tvar rendered string\n\tm := NewManagerWithRunner(func(_ context.Context, script string) ([]byte, error) {\n\t\trendered = script\n\t\treturn nil, nil\n\t})\n\tips := []ResolvedIP{\n\t\t{Addr: netip.MustParseAddr(\"10.0.0.1\"), TTL: 10 * time.Second},\n\t\t{Addr: netip.MustParseAddr(\"10.0.0.2\"), TTL: 9999 * time.Second},\n\t}\n\trequire.NoError(t, m.AddResolvedIPs(context.Background(), ips), \"AddResolvedIPs returned error\")\n\texpectContains(t, rendered, \"10.0.0.1 timeout 60s\")\n\texpectContains(t, rendered, \"10.0.0.2 timeout 300s\")\n}\n\nfunc TestAddResolvedIPs_EmptyNoOp(t *testing.T) {\n\tm := NewManagerWithRunner(func(_ context.Context, script string) ([]byte, error) {\n\t\trequire.FailNow(t, \"runner should not be called for empty ips\")\n\t\treturn nil, nil\n\t})\n\trequire.NoError(t, m.AddResolvedIPs(context.Background(), nil), \"AddResolvedIPs returned error\")\n\trequire.NoError(t, m.AddResolvedIPs(context.Background(), []ResolvedIP{}), \"AddResolvedIPs returned error\")\n}\n" }, { "path": "components/egress/pkg/policy/policy.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage policy\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/netip\"\n\t\"strings\"\n)\n\nconst (\n\tActionAllow = \"allow\"\n\tActionDeny = \"deny\"\n)\n\ntype targetKind int\n\nconst (\n\ttargetUnknown targetKind = iota\n\ttargetDomain\n\ttargetIP\n\ttargetCIDR\n)\n\n// DefaultDenyPolicy returns a new policy that denies all traffic.\nfunc DefaultDenyPolicy() *NetworkPolicy {\n\treturn &NetworkPolicy{DefaultAction: ActionDeny}\n}\n\n// NetworkPolicy is the minimal MVP shape for egress control.\n// Only domain/wildcard targets are honored in this MVP.\ntype NetworkPolicy struct {\n\tEgress []EgressRule `json:\"egress\"`\n\tDefaultAction string `json:\"defaultAction\"`\n}\n\ntype EgressRule struct {\n\tAction string `json:\"action\"`\n\tTarget string `json:\"target\"`\n\n\ttargetKind targetKind\n\tip netip.Addr\n\tprefix netip.Prefix\n}\n\n// ParsePolicy parses JSON from env/config into a NetworkPolicy.\n// Default action falls back to \"deny\" to align with proposal.\nfunc ParsePolicy(raw string) (*NetworkPolicy, error) {\n\ttrimmed := strings.TrimSpace(raw)\n\tif trimmed == \"\" || trimmed == \"null\" || trimmed == \"{}\" {\n\t\treturn DefaultDenyPolicy(), nil\n\t}\n\n\tvar p NetworkPolicy\n\tif err := json.Unmarshal([]byte(trimmed), &p); err != nil {\n\t\treturn nil, err\n\t}\n\tif err := normalizePolicy(&p); err != nil {\n\t\treturn nil, err\n\t}\n\treturn ensureDefaults(&p), nil\n}\n\n// Evaluate returns allow/deny for a given domain (lowercased).\nfunc (p *NetworkPolicy) Evaluate(domain string) string {\n\tif p == nil {\n\t\treturn ActionDeny\n\t}\n\tdomain = strings.ToLower(strings.TrimSuffix(domain, \".\"))\n\tfor _, r := range p.Egress {\n\t\tif r.targetKind != targetDomain {\n\t\t\tcontinue\n\t\t}\n\t\tif r.matchesDomain(domain) {\n\t\t\tif r.Action == \"\" {\n\t\t\t\treturn ActionDeny\n\t\t\t}\n\t\t\treturn r.Action\n\t\t}\n\t}\n\tif p.DefaultAction == \"\" {\n\t\treturn ActionDeny\n\t}\n\treturn p.DefaultAction\n}\n\n// ensureDefaults guarantees a policy always has a default action.\nfunc ensureDefaults(p *NetworkPolicy) *NetworkPolicy {\n\tif p == nil {\n\t\treturn DefaultDenyPolicy()\n\t}\n\tif p.DefaultAction == \"\" {\n\t\tp.DefaultAction = ActionDeny\n\t}\n\treturn p\n}\n\nfunc normalizePolicy(p *NetworkPolicy) error {\n\tp.DefaultAction = strings.ToLower(strings.TrimSpace(p.DefaultAction))\n\tif p.DefaultAction == \"\" {\n\t\tp.DefaultAction = ActionDeny\n\t}\n\n\tfor i := range p.Egress {\n\t\tr := &p.Egress[i]\n\t\tr.Action = strings.ToLower(strings.TrimSpace(r.Action))\n\t\tif r.Action == \"\" {\n\t\t\tr.Action = ActionDeny\n\t\t}\n\t\tif r.Action != ActionAllow && r.Action != ActionDeny {\n\t\t\treturn fmt.Errorf(\"unsupported action %q\", r.Action)\n\t\t}\n\n\t\tr.Target = strings.TrimSpace(r.Target)\n\t\tif r.Target == \"\" {\n\t\t\treturn fmt.Errorf(\"egress target cannot be empty\")\n\t\t}\n\t\tif ip, err := netip.ParseAddr(r.Target); err == nil {\n\t\t\tr.targetKind = targetIP\n\t\t\tr.ip = ip\n\t\t\tcontinue\n\t\t}\n\t\tif prefix, err := netip.ParsePrefix(r.Target); err == nil {\n\t\t\tr.targetKind = targetCIDR\n\t\t\tr.prefix = prefix\n\t\t\tcontinue\n\t\t}\n\t\tr.targetKind = targetDomain\n\t}\n\treturn nil\n}\n\n// WithExtraAllowIPs returns a copy of the policy with additional allow rules for each IP.\n// Used at startup to whitelist system nameservers so client DNS and proxy upstream work with private DNS.\nfunc (p *NetworkPolicy) WithExtraAllowIPs(ips []netip.Addr) *NetworkPolicy {\n\tif p == nil || len(ips) == 0 {\n\t\treturn p\n\t}\n\tout := *p\n\tout.Egress = make([]EgressRule, len(p.Egress), len(p.Egress)+len(ips))\n\tcopy(out.Egress, p.Egress)\n\tfor _, ip := range ips {\n\t\tout.Egress = append(out.Egress, EgressRule{\n\t\t\tAction: ActionAllow,\n\t\t\tTarget: ip.String(),\n\t\t\ttargetKind: targetIP,\n\t\t\tip: ip,\n\t\t})\n\t}\n\treturn &out\n}\n\n// StaticIPSets splits static IP/CIDR rules into allow/deny IPv4/IPv6 buckets.\n// Empty or nil policy returns empty slices.\nfunc (p *NetworkPolicy) StaticIPSets() (allowV4, allowV6, denyV4, denyV6 []string) {\n\tif p == nil {\n\t\treturn\n\t}\n\tfor _, r := range p.Egress {\n\t\tswitch r.targetKind {\n\t\tcase targetIP:\n\t\t\taddr := r.ip\n\t\t\ttarget := addr.String()\n\t\t\tif r.Action == ActionAllow {\n\t\t\t\tif addr.Is4() {\n\t\t\t\t\tallowV4 = append(allowV4, target)\n\t\t\t\t} else if addr.Is6() {\n\t\t\t\t\tallowV6 = append(allowV6, target)\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tif addr.Is4() {\n\t\t\t\t\tdenyV4 = append(denyV4, target)\n\t\t\t\t} else if addr.Is6() {\n\t\t\t\t\tdenyV6 = append(denyV6, target)\n\t\t\t\t}\n\t\t\t}\n\t\tcase targetCIDR:\n\t\t\tpfx := r.prefix\n\t\t\ttarget := pfx.String()\n\t\t\tif r.Action == ActionAllow {\n\t\t\t\tif pfx.Addr().Is4() {\n\t\t\t\t\tallowV4 = append(allowV4, target)\n\t\t\t\t} else if pfx.Addr().Is6() {\n\t\t\t\t\tallowV6 = append(allowV6, target)\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tif pfx.Addr().Is4() {\n\t\t\t\t\tdenyV4 = append(denyV4, target)\n\t\t\t\t} else if pfx.Addr().Is6() {\n\t\t\t\t\tdenyV6 = append(denyV6, target)\n\t\t\t\t}\n\t\t\t}\n\t\tdefault:\n\t\t\tcontinue\n\t\t}\n\t}\n\treturn\n}\n\nfunc (r *EgressRule) matchesDomain(domain string) bool {\n\tpattern := strings.ToLower(strings.TrimSpace(r.Target))\n\tdomain = strings.ToLower(domain)\n\n\tif pattern == \"\" {\n\t\treturn false\n\t}\n\tif pattern == domain {\n\t\treturn true\n\t}\n\tif strings.HasPrefix(pattern, \"*.\") {\n\t\t// \"*.example.com\" matches \"a.example.com\" but not \"example.com\"\n\t\tsuffix := strings.TrimPrefix(pattern, \"*\")\n\t\treturn strings.HasSuffix(domain, suffix) && domain != strings.TrimPrefix(pattern, \"*.\")\n\t}\n\treturn false\n}\n" }, { "path": "components/egress/pkg/policy/policy_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage policy\n\nimport (\n\t\"net/netip\"\n\t\"testing\"\n\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestParsePolicy_EmptyOrNullDefaultsDeny(t *testing.T) {\n\tcases := []string{\n\t\t\"\",\n\t\t\" \",\n\t\t\"null\",\n\t\t\"{}\\n\",\n\t}\n\tfor _, raw := range cases {\n\t\tp, err := ParsePolicy(raw)\n\t\trequire.NoErrorf(t, err, \"raw %q returned error\", raw)\n\t\trequire.NotNilf(t, p, \"raw %q expected default deny policy, got nil\", raw)\n\t\trequire.Equalf(t, ActionDeny, p.DefaultAction, \"raw %q expected defaultAction deny\", raw)\n\t\trequire.Equalf(t, ActionDeny, p.Evaluate(\"example.com.\"), \"raw %q expected deny evaluation\", raw)\n\t}\n}\n\nfunc TestParsePolicy_DefaultActionFallback(t *testing.T) {\n\tp, err := ParsePolicy(`{\"egress\":[{\"action\":\"allow\",\"target\":\"example.com\"}]}`)\n\trequire.NoError(t, err)\n\trequire.NotNil(t, p, \"expected policy object, got nil\")\n\trequire.Equal(t, ActionDeny, p.DefaultAction, \"expected defaultAction fallback to deny\")\n}\n\nfunc TestParsePolicy_EmptyEgressDefaultsDeny(t *testing.T) {\n\tp, err := ParsePolicy(`{\"defaultAction\":\"\"}`)\n\trequire.NoError(t, err)\n\trequire.Equal(t, ActionDeny, p.DefaultAction, \"expected default deny when defaultAction missing\")\n\trequire.Equal(t, ActionDeny, p.Evaluate(\"anything.com.\"), \"expected evaluation deny for empty egress\")\n}\n\nfunc TestParsePolicy_IPAndCIDRSupported(t *testing.T) {\n\traw := `{\n\t\t\"defaultAction\":\"deny\",\n\t\t\"egress\":[\n\t\t\t{\"action\":\"allow\",\"target\":\"1.1.1.1\"},\n\t\t\t{\"action\":\"allow\",\"target\":\"2.2.0.0/16\"},\n\t\t\t{\"action\":\"deny\",\"target\":\"2001:db8::/32\"},\n\t\t\t{\"action\":\"deny\",\"target\":\"2001:db8::1\"}\n\t\t]\n\t}`\n\tp, err := ParsePolicy(raw)\n\trequire.NoError(t, err)\n\tallowV4, allowV6, denyV4, denyV6 := p.StaticIPSets()\n\trequire.Len(t, allowV4, 2, \"allowV4 length mismatch\")\n\trequire.Equal(t, \"1.1.1.1\", allowV4[0])\n\trequire.Equal(t, \"2.2.0.0/16\", allowV4[1])\n\trequire.Len(t, denyV6, 2, \"expected 2 denyV6 entries\")\n\trequire.Empty(t, allowV6, \"allowV6 should be empty\")\n\trequire.Empty(t, denyV4, \"denyV4 should be empty\")\n}\n\nfunc TestParsePolicy_InvalidAction(t *testing.T) {\n\t_, err := ParsePolicy(`{\"egress\":[{\"action\":\"foo\",\"target\":\"example.com\"}]}`)\n\trequire.Error(t, err, \"expected error for invalid action\")\n}\n\nfunc TestParsePolicy_EmptyTargetError(t *testing.T) {\n\t_, err := ParsePolicy(`{\"egress\":[{\"action\":\"allow\",\"target\":\"\"}]}`)\n\trequire.Error(t, err, \"expected error for empty target\")\n}\n\nfunc TestWithExtraAllowIPs(t *testing.T) {\n\tp, err := ParsePolicy(`{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"example.com\"}]}`)\n\trequire.NoError(t, err)\n\tallowV4, allowV6, _, _ := p.StaticIPSets()\n\trequire.Empty(t, allowV4, \"domain-only policy should have no static allowV4 IPs\")\n\trequire.Empty(t, allowV6, \"domain-only policy should have no static allowV6 IPs\")\n\n\tips := []netip.Addr{\n\t\tnetip.MustParseAddr(\"192.168.65.7\"),\n\t\tnetip.MustParseAddr(\"2001:db8::1\"),\n\t}\n\tmerged := p.WithExtraAllowIPs(ips)\n\trequire.NotSame(t, p, merged, \"expected new policy instance\")\n\tallowV4, allowV6, _, _ = merged.StaticIPSets()\n\trequire.Len(t, allowV4, 1, \"allowV4 length mismatch\")\n\trequire.Equal(t, \"192.168.65.7\", allowV4[0])\n\trequire.Len(t, allowV6, 1, \"allowV6 length mismatch\")\n\trequire.Equal(t, \"2001:db8::1\", allowV6[0])\n\n\t// nil/empty ips returns same policy\n\trequire.Same(t, p, p.WithExtraAllowIPs(nil), \"WithExtraAllowIPs(nil) should return same policy\")\n\trequire.Same(t, p, p.WithExtraAllowIPs([]netip.Addr{}), \"WithExtraAllowIPs([]) should return same policy\")\n}\n" }, { "path": "components/egress/policy_server.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"context\"\n\t\"crypto/subtle\"\n\t\"encoding/json\"\n\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"net/netip\"\n\t\"strings\"\n\t\"sync\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/constants\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/log\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/nftables\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/policy\"\n)\n\ntype policyUpdater interface {\n\tCurrentPolicy() *policy.NetworkPolicy\n\tUpdatePolicy(*policy.NetworkPolicy)\n}\n\n// enforcementReporter reports the current enforcement mode (dns | dns+nft).\ntype enforcementReporter interface {\n\tEnforcementMode() string\n}\n\n// nftApplier applies static policy and optional dynamic DNS-learned IPs to nftables.\ntype nftApplier interface {\n\tApplyStatic(context.Context, *policy.NetworkPolicy) error\n\tAddResolvedIPs(context.Context, []nftables.ResolvedIP) error\n}\n\n// startPolicyServer launches a lightweight HTTP API for updating the egress policy at runtime.\n// Supported endpoints:\n// - GET /policy : returns the currently enforced policy.\n// - POST /policy : replace the policy; empty body resets to default deny-all.\n//\n// nameserverIPs are merged into every applied policy so system DNS stays allowed (e.g. private DNS).\nfunc startPolicyServer(ctx context.Context, proxy policyUpdater, nft nftApplier, enforcementMode string, addr string, token string, nameserverIPs []netip.Addr) error {\n\tmux := http.NewServeMux()\n\thandler := &policyServer{proxy: proxy, nft: nft, token: token, enforcementMode: enforcementMode, nameserverIPs: nameserverIPs}\n\tmux.HandleFunc(\"/policy\", handler.handlePolicy)\n\tmux.HandleFunc(\"/healthz\", func(w http.ResponseWriter, _ *http.Request) {\n\t\tw.WriteHeader(http.StatusOK)\n\t\t_, _ = w.Write([]byte(\"ok\"))\n\t})\n\n\tsrv := &http.Server{Addr: addr, Handler: mux}\n\thandler.server = srv\n\n\t// Shutdown listener when context ends.\n\tgo func() {\n\t\t<-ctx.Done()\n\t\tshutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\t\tdefer cancel()\n\t\tif err := srv.Shutdown(shutdownCtx); err != nil && !errors.Is(err, http.ErrServerClosed) {\n\t\t\tlog.Warnf(\"policy server shutdown error: %v\", err)\n\t\t}\n\t}()\n\n\terrCh := make(chan error, 1)\n\tgo func() {\n\t\tif err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {\n\t\t\terrCh <- err\n\t\t}\n\t}()\n\n\tselect {\n\tcase err := <-errCh:\n\t\treturn err\n\tcase <-time.After(200 * time.Millisecond):\n\t\t// assume healthy start; keep logging future errors\n\t\tgo func() {\n\t\t\tif err := <-errCh; err != nil {\n\t\t\t\tlog.Errorf(\"policy server error: %v\", err)\n\t\t\t}\n\t\t}()\n\t\treturn nil\n\t}\n}\n\ntype policyServer struct {\n\tproxy policyUpdater\n\tnft nftApplier\n\tserver *http.Server\n\ttoken string\n\tenforcementMode string\n\tnameserverIPs []netip.Addr\n\tmu sync.Mutex // serializes read-merge-apply to avoid lost updates across POST/PATCH\n}\n\ntype policyStatusResponse struct {\n\tStatus string `json:\"status,omitempty\"`\n\tMode string `json:\"mode,omitempty\"`\n\tEnforcementMode string `json:\"enforcementMode,omitempty\"`\n\tReason string `json:\"reason,omitempty\"`\n\tPolicy any `json:\"policy,omitempty\"`\n}\n\nfunc (s *policyServer) handlePolicy(w http.ResponseWriter, r *http.Request) {\n\tif !s.authorize(r) {\n\t\thttp.Error(w, \"unauthorized\", http.StatusUnauthorized)\n\t\treturn\n\t}\n\tswitch r.Method {\n\tcase http.MethodGet:\n\t\ts.handleGet(w)\n\tcase http.MethodPost, http.MethodPut:\n\t\ts.handlePost(w, r)\n\tcase http.MethodPatch:\n\t\ts.handlePatch(w, r)\n\tdefault:\n\t\tw.Header().Set(\"Allow\", \"GET, POST, PUT, PATCH\")\n\t\thttp.Error(w, \"method not allowed\", http.StatusMethodNotAllowed)\n\t}\n}\n\nfunc (s *policyServer) handleGet(w http.ResponseWriter) {\n\tcurrent := s.proxy.CurrentPolicy()\n\tmode := modeFromPolicy(current)\n\twriteJSON(w, http.StatusOK, policyStatusResponse{\n\t\tStatus: \"ok\",\n\t\tMode: mode,\n\t\tEnforcementMode: s.enforcementMode,\n\t\tPolicy: current,\n\t})\n}\n\nfunc (s *policyServer) handlePost(w http.ResponseWriter, r *http.Request) {\n\tdefer r.Body.Close()\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()\n\n\tbody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20)) // 1MB limit\n\tif err != nil {\n\t\thttp.Error(w, fmt.Sprintf(\"failed to read body: %v\", err), http.StatusBadRequest)\n\t\treturn\n\t}\n\traw := strings.TrimSpace(string(body))\n\tif raw == \"\" {\n\t\tlog.Infof(\"policy API: reset to default deny-all\")\n\t\tdef := policy.DefaultDenyPolicy()\n\t\tif s.nft != nil {\n\t\t\tdefWithNS := def.WithExtraAllowIPs(s.nameserverIPs)\n\t\t\tif err := s.nft.ApplyStatic(r.Context(), defWithNS); err != nil {\n\t\t\t\tlog.Errorf(\"policy API: nftables apply failed on reset: %v\", err)\n\t\t\t\thttp.Error(w, fmt.Sprintf(\"failed to apply nftables: %v\", err), http.StatusInternalServerError)\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\t\ts.proxy.UpdatePolicy(def)\n\t\tlog.Infof(\"policy API: proxy and nftables updated to deny_all\")\n\t\twriteJSON(w, http.StatusOK, policyStatusResponse{\n\t\t\tStatus: \"ok\",\n\t\t\tMode: \"deny_all\",\n\t\t\tReason: \"policy reset to default deny-all\",\n\t\t})\n\t\treturn\n\t}\n\n\tpol, err := policy.ParsePolicy(raw)\n\tif err != nil {\n\t\thttp.Error(w, fmt.Sprintf(\"invalid policy: %v\", err), http.StatusBadRequest)\n\t\treturn\n\t}\n\tmode := modeFromPolicy(pol)\n\tlog.Infof(\"policy API: updating policy to mode=%s, enforcement=%s\", mode, s.enforcementMode)\n\tif s.nft != nil {\n\t\tpolWithNS := pol.WithExtraAllowIPs(s.nameserverIPs)\n\t\tif err := s.nft.ApplyStatic(r.Context(), polWithNS); err != nil {\n\t\t\tlog.Errorf(\"policy API: nftables apply failed: %v\", err)\n\t\t\thttp.Error(w, fmt.Sprintf(\"failed to apply nftables policy: %v\", err), http.StatusInternalServerError)\n\t\t\treturn\n\t\t}\n\t}\n\ts.proxy.UpdatePolicy(pol)\n\tlog.Infof(\"policy API: proxy and nftables updated successfully\")\n\twriteJSON(w, http.StatusOK, policyStatusResponse{\n\t\tStatus: \"ok\",\n\t\tMode: mode,\n\t\tEnforcementMode: s.enforcementMode,\n\t})\n}\n\n// handlePatch adds or replaces egress rules by merging with the current policy.\n// It is a convenience wrapper over the full replace flow: we still read -> merge -> apply.\n// Request body supports {\"egress\":[{\"action\":\"allow\",\"target\":\"example.com\"}, ...]}.\nfunc (s *policyServer) handlePatch(w http.ResponseWriter, r *http.Request) {\n\tdefer r.Body.Close()\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()\n\n\tbody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20)) // 1MB limit\n\tif err != nil {\n\t\thttp.Error(w, fmt.Sprintf(\"failed to read body: %v\", err), http.StatusBadRequest)\n\t\treturn\n\t}\n\traw := strings.TrimSpace(string(body))\n\tif raw == \"\" {\n\t\thttp.Error(w, \"patch body cannot be empty\", http.StatusBadRequest)\n\t\treturn\n\t}\n\n\tvar patchRules []policy.EgressRule\n\tif err = json.Unmarshal([]byte(raw), &patchRules); err != nil {\n\t\thttp.Error(w, fmt.Sprintf(\"invalid patch rules: %v\", err), http.StatusBadRequest)\n\t\treturn\n\t}\n\tif len(patchRules) == 0 {\n\t\thttp.Error(w, \"patch must include at least one egress rule\", http.StatusBadRequest)\n\t\treturn\n\t}\n\n\tbase := s.proxy.CurrentPolicy()\n\tif base == nil {\n\t\tbase = policy.DefaultDenyPolicy()\n\t}\n\tbaseCopy := *base\n\tbaseCopy.Egress = append([]policy.EgressRule(nil), base.Egress...)\n\n\tmerged := mergeEgressRules(baseCopy.Egress, patchRules)\n\n\t// Reuse parser to normalize targets/actions.\n\trawMerged, _ := json.Marshal(policy.NetworkPolicy{\n\t\tDefaultAction: baseCopy.DefaultAction,\n\t\tEgress: merged,\n\t})\n\tnewPolicy, err := policy.ParsePolicy(string(rawMerged))\n\tif err != nil {\n\t\thttp.Error(w, fmt.Sprintf(\"invalid merged policy: %v\", err), http.StatusBadRequest)\n\t\treturn\n\t}\n\n\tmode := modeFromPolicy(newPolicy)\n\tlog.Infof(\"policy API: patching policy with %d new rule(s), mode=%s, enforcement=%s\", len(patchRules), mode, s.enforcementMode)\n\tif s.nft != nil {\n\t\tpolWithNS := newPolicy.WithExtraAllowIPs(s.nameserverIPs)\n\t\tif err := s.nft.ApplyStatic(r.Context(), polWithNS); err != nil {\n\t\t\tlog.Errorf(\"policy API: nftables apply failed on patch: %v\", err)\n\t\t\thttp.Error(w, fmt.Sprintf(\"failed to apply nftables policy: %v\", err), http.StatusInternalServerError)\n\t\t\treturn\n\t\t}\n\t}\n\ts.proxy.UpdatePolicy(newPolicy)\n\tlog.Infof(\"policy API: patch applied successfully\")\n\twriteJSON(w, http.StatusOK, policyStatusResponse{\n\t\tStatus: \"ok\",\n\t\tMode: mode,\n\t\tEnforcementMode: s.enforcementMode,\n\t})\n}\n\nfunc (s *policyServer) authorize(r *http.Request) bool {\n\tif s.token == \"\" {\n\t\treturn true\n\t}\n\tprovided := r.Header.Get(constants.EgressAuthTokenHeader)\n\tif provided == \"\" {\n\t\treturn false\n\t}\n\tif len(provided) != len(s.token) {\n\t\treturn false\n\t}\n\treturn subtle.ConstantTimeCompare([]byte(provided), []byte(s.token)) == 1\n}\n\nfunc writeJSON(w http.ResponseWriter, status int, payload any) {\n\tw.Header().Set(\"Content-Type\", \"application/json\")\n\tw.WriteHeader(status)\n\t_ = json.NewEncoder(w).Encode(payload)\n}\n\nfunc modeFromPolicy(p *policy.NetworkPolicy) string {\n\tif p == nil {\n\t\treturn \"deny_all\"\n\t}\n\tif p.DefaultAction == policy.ActionAllow && len(p.Egress) == 0 {\n\t\treturn \"allow_all\"\n\t} else if p.DefaultAction == policy.ActionDeny && len(p.Egress) == 0 {\n\t\treturn \"deny_all\"\n\t}\n\n\treturn \"enforcing\"\n}\n\n// mergeEgressRules joins base rules and additions, deduping by target (last writer wins).\nfunc mergeEgressRules(base, additions []policy.EgressRule) []policy.EgressRule {\n\tif len(additions) == 0 {\n\t\treturn base\n\t}\n\tout := make([]policy.EgressRule, 0, len(base)+len(additions))\n\tseen := make(map[string]struct{})\n\n\t// Priority: additions first; base rules only if target not overridden.\n\tfor _, r := range additions {\n\t\tkey := mergeKey(r)\n\t\tif _, ok := seen[key]; ok {\n\t\t\tcontinue\n\t\t}\n\t\tseen[key] = struct{}{}\n\t\tout = append(out, r)\n\t}\n\tfor _, r := range base {\n\t\tkey := mergeKey(r)\n\t\tif _, ok := seen[key]; ok {\n\t\t\tcontinue\n\t\t}\n\t\tseen[key] = struct{}{}\n\t\tout = append(out, r)\n\t}\n\treturn out\n}\n\n// mergeKey normalizes domain targets to lowercase for dedupe;\n// IP/CIDR targets are kept as-is.\nfunc mergeKey(r policy.EgressRule) string {\n\tif r.Target == \"\" {\n\t\treturn r.Target\n\t}\n\treturn strings.ToLower(r.Target)\n}\n" }, { "path": "components/egress/policy_server_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"io\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"strings\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/egress/pkg/nftables\"\n\t\"github.com/alibaba/opensandbox/egress/pkg/policy\"\n\t\"github.com/stretchr/testify/require\"\n)\n\ntype stubProxy struct {\n\tupdated *policy.NetworkPolicy\n}\n\nfunc (s *stubProxy) CurrentPolicy() *policy.NetworkPolicy {\n\treturn s.updated\n}\n\nfunc (s *stubProxy) UpdatePolicy(p *policy.NetworkPolicy) {\n\ts.updated = p\n}\n\ntype stubNft struct {\n\terr error\n\tcalls int\n\tapplied *policy.NetworkPolicy\n}\n\nfunc (s *stubNft) ApplyStatic(_ context.Context, p *policy.NetworkPolicy) error {\n\ts.calls++\n\ts.applied = p\n\treturn s.err\n}\n\nfunc (s *stubNft) AddResolvedIPs(_ context.Context, _ []nftables.ResolvedIP) error {\n\treturn nil\n}\n\nfunc TestHandlePolicy_AppliesNftAndUpdatesProxy(t *testing.T) {\n\tproxy := &stubProxy{}\n\tnft := &stubNft{}\n\tsrv := &policyServer{proxy: proxy, nft: nft, enforcementMode: \"dns+nft\"}\n\n\tbody := `{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"1.1.1.1\"}]}`\n\treq := httptest.NewRequest(http.MethodPost, \"/policy\", strings.NewReader(body))\n\tw := httptest.NewRecorder()\n\n\tsrv.handlePolicy(w, req)\n\n\tresp := w.Result()\n\trequire.Equal(t, http.StatusOK, resp.StatusCode, \"expected 200 OK\")\n\trequire.Contains(t, resp.Header.Get(\"Content-Type\"), \"application/json\", \"expected json response\")\n\trequire.Equal(t, 1, nft.calls, \"expected nft ApplyStatic called once\")\n\trequire.NotNil(t, proxy.updated, \"expected proxy policy to be updated\")\n\trequire.Equal(t, policy.ActionDeny, proxy.updated.DefaultAction, \"unexpected defaultAction\")\n}\n\nfunc TestHandlePolicy_NftFailureReturns500(t *testing.T) {\n\tproxy := &stubProxy{}\n\tnft := &stubNft{err: errors.New(\"boom\")}\n\tsrv := &policyServer{proxy: proxy, nft: nft, enforcementMode: \"dns+nft\"}\n\n\tbody := `{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"1.1.1.1\"}]}`\n\treq := httptest.NewRequest(http.MethodPost, \"/policy\", strings.NewReader(body))\n\tw := httptest.NewRecorder()\n\n\tsrv.handlePolicy(w, req)\n\n\tresp := w.Result()\n\trequire.Equal(t, http.StatusInternalServerError, resp.StatusCode, \"expected 500\")\n\trequire.Equal(t, 1, nft.calls, \"expected nft ApplyStatic called once\")\n\trequire.Nil(t, proxy.updated, \"expected proxy policy not updated on nft failure\")\n}\n\nfunc TestHandleGet_ReturnsEnforcementMode(t *testing.T) {\n\tproxy := &stubProxy{updated: policy.DefaultDenyPolicy()}\n\tsrv := &policyServer{proxy: proxy, nft: nil, enforcementMode: \"dns\"}\n\n\treq := httptest.NewRequest(http.MethodGet, \"/policy\", nil)\n\tw := httptest.NewRecorder()\n\n\tsrv.handlePolicy(w, req)\n\n\tresp := w.Result()\n\trequire.Equal(t, http.StatusOK, resp.StatusCode, \"expected 200\")\n\tbody, err := io.ReadAll(resp.Body)\n\trequire.NoError(t, err)\n\trequire.Contains(t, string(body), `\"enforcementMode\":\"dns\"`, \"expected enforcementMode dns in response\")\n}\n\nfunc TestHandlePatch_MergesAndApplies(t *testing.T) {\n\tinitial := &policy.NetworkPolicy{\n\t\tDefaultAction: policy.ActionDeny,\n\t\tEgress: []policy.EgressRule{\n\t\t\t{Action: policy.ActionAllow, Target: \"example.com\"},\n\t\t\t{Action: policy.ActionDeny, Target: \"*.example.com\"},\n\t\t},\n\t}\n\tproxy := &stubProxy{updated: initial}\n\tnft := &stubNft{}\n\tsrv := &policyServer{proxy: proxy, nft: nft, enforcementMode: \"dns+nft\"}\n\n\tbody := `[{\"action\":\"deny\",\"target\":\"blocked.com\"},{\"action\":\"allow\",\"target\":\"example.com\"}]`\n\treq := httptest.NewRequest(http.MethodPatch, \"/policy\", strings.NewReader(body))\n\tw := httptest.NewRecorder()\n\n\tsrv.handlePolicy(w, req)\n\n\tresp := w.Result()\n\trequire.Equal(t, http.StatusOK, resp.StatusCode, \"expected 200\")\n\trequire.Equal(t, 1, nft.calls, \"expected nft ApplyStatic called once\")\n\trequire.NotNil(t, proxy.updated, \"expected proxy policy to be updated\")\n\trequire.Equal(t, policy.ActionDeny, proxy.updated.DefaultAction, \"default action should be preserved\")\n\trequire.Len(t, proxy.updated.Egress, 3, \"expected 3 egress rules\")\n\trequire.Equal(t, policy.ActionDeny, proxy.updated.Egress[0].Action, \"first rule action mismatch\")\n\trequire.Equal(t, \"blocked.com\", proxy.updated.Egress[0].Target, \"first rule target mismatch\")\n\trequire.Equal(t, policy.ActionAllow, proxy.updated.Egress[1].Action, \"second rule action mismatch\")\n\trequire.Equal(t, \"example.com\", proxy.updated.Egress[1].Target, \"second rule target mismatch\")\n\trequire.Equal(t, policy.ActionDeny, proxy.updated.Egress[2].Action, \"base wildcard rule action mismatch\")\n\trequire.Equal(t, \"*.example.com\", proxy.updated.Egress[2].Target, \"base wildcard rule target mismatch\")\n}\n\nfunc TestHandlePatch_DomainCaseOverride(t *testing.T) {\n\tinitial := &policy.NetworkPolicy{\n\t\tDefaultAction: policy.ActionDeny,\n\t\tEgress: []policy.EgressRule{\n\t\t\t{Action: policy.ActionDeny, Target: \"Example.COM\"},\n\t\t},\n\t}\n\tproxy := &stubProxy{updated: initial}\n\tnft := &stubNft{}\n\tsrv := &policyServer{proxy: proxy, nft: nft, enforcementMode: \"dns+nft\"}\n\n\tbody := `[{\"action\":\"allow\",\"target\":\"example.com\"}]`\n\treq := httptest.NewRequest(http.MethodPatch, \"/policy\", strings.NewReader(body))\n\tw := httptest.NewRecorder()\n\n\tsrv.handlePolicy(w, req)\n\n\tresp := w.Result()\n\trequire.Equal(t, http.StatusOK, resp.StatusCode, \"expected 200\")\n\trequire.NotNil(t, proxy.updated, \"expected proxy policy to be updated\")\n\trequire.Len(t, proxy.updated.Egress, 1, \"expected deduped rule count 1\")\n\trequire.Equal(t, policy.ActionAllow, proxy.updated.Egress[0].Action, \"expected allow action\")\n\trequire.Equal(t, \"example.com\", proxy.updated.Egress[0].Target, \"expected allow example.com to override\")\n}\n" }, { "path": "components/egress/tests/bench-dns-nft.sh", "content": "#!/bin/bash\n\n# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n# E2E benchmark: baseline (no egress) vs dns (pass-through) vs dns+nft (sync dynamic IP write).\n# Baseline: plain curl container, same workload, no container. Then egress dns and dns+nft.\n# Metrics: E2E latency (p50, p99), throughput (req/s).\n#\n# Usage: ./tests/bench-dns-nft.sh\n# Optional: BENCH_SAMPLE_SIZE=n to randomly use n domains from hostname.txt (default: use all).\n# Requires: Docker, curl in PATH (for policy push). Egress image and baseline image (default curlimages/curl:latest) must have curl.\n# Domain list: tests/hostname.txt (one domain per line).\n\nset -euo pipefail\n\ninfo() { echo \"[$(date +%H:%M:%S)] $*\"; }\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nHOSTNAME_FILE=\"${SCRIPT_DIR}/hostname.txt\"\n# tests/ is two levels under repo root: components/egress/tests -> climb 3 levels.\nREPO_ROOT=\"$(cd \"${SCRIPT_DIR}/../../..\" && pwd)\"\n\nIMG=\"opensandbox/egress:local\"\nBASELINE_IMG=\"${BASELINE_IMG:-curlimages/curl:latest}\"\nCONTAINER_NAME=\"egress-bench-e2e\"\nPOLICY_PORT=18080\nROUNDS=10\n# Optional: where to write egress logs on host. Override via LOG_HOST_DIR / LOG_FILE.\nLOG_HOST_DIR=\"${LOG_HOST_DIR:-/tmp/egress-logs}\"\nLOG_FILE=\"${LOG_FILE:-egress.log}\"\nLOG_CONTAINER_DIR=\"/var/log/opensandbox\"\nLOG_CONTAINER_FILE=\"${LOG_CONTAINER_DIR}/${LOG_FILE}\"\n\n# Load benchmark domains from hostname.txt (one domain per line).\nif [[ ! -f \"${HOSTNAME_FILE}\" ]] || [[ ! -s \"${HOSTNAME_FILE}\" ]]; then\n echo \"Error: domain file not found or empty: ${HOSTNAME_FILE}\" >&2\n exit 1\nfi\nBENCH_DOMAINS=()\nwhile IFS= read -r line; do\n line=\"${line%%#*}\"\n line=\"${line#\"${line%%[![:space:]]*}\"}\"\n line=\"${line%\"${line##*[![:space:]]}\"}\"\n [[ -n \"$line\" ]] && BENCH_DOMAINS+=( \"$line\" )\ndone < \"${HOSTNAME_FILE}\"\ntotal_in_file=${#BENCH_DOMAINS[@]}\nif [[ \"$total_in_file\" -eq 0 ]]; then\n echo \"Error: no domains in ${HOSTNAME_FILE}\" >&2\n exit 1\nfi\n\n# Optionally randomly sample n domains (BENCH_SAMPLE_SIZE); if unset or 0, use all.\nif [[ -n \"${BENCH_SAMPLE_SIZE:-}\" ]] && [[ \"${BENCH_SAMPLE_SIZE}\" -gt 0 ]]; then\n if [[ \"${BENCH_SAMPLE_SIZE}\" -ge \"$total_in_file\" ]]; then\n NUM_DOMAINS=$total_in_file\n else\n # Portable shuffle: shuf (Linux), gshuf (macOS coreutils), else awk\n if command -v shuf >/dev/null 2>&1; then\n BENCH_DOMAINS=( $(printf '%s\\n' \"${BENCH_DOMAINS[@]}\" | shuf -n \"${BENCH_SAMPLE_SIZE}\") )\n elif command -v gshuf >/dev/null 2>&1; then\n BENCH_DOMAINS=( $(printf '%s\\n' \"${BENCH_DOMAINS[@]}\" | gshuf -n \"${BENCH_SAMPLE_SIZE}\") )\n else\n BENCH_DOMAINS=( $(printf '%s\\n' \"${BENCH_DOMAINS[@]}\" | awk 'BEGIN{srand()} {printf \"%s\\t%s\\n\", rand(), $0}' | sort -n | cut -f2- | head -n \"${BENCH_SAMPLE_SIZE}\") )\n fi\n NUM_DOMAINS=${#BENCH_DOMAINS[@]}\n info \"Using ${NUM_DOMAINS} randomly sampled domains (of ${total_in_file}) from ${HOSTNAME_FILE}\"\n fi\nelse\n NUM_DOMAINS=$total_in_file\nfi\nTOTAL_REQUESTS=$((ROUNDS * NUM_DOMAINS))\nCURL_TIMEOUT=10\n# Max wall time for the benchmark loop (docker exec); avoid hanging forever.\nBENCH_EXEC_TIMEOUT=300\n\ncleanup() {\n docker rm -f \"${CONTAINER_NAME}\" >/dev/null 2>&1 || true\n}\ntrap cleanup EXIT\n\n# Compute stats from a file with one numeric value per line (e.g. time_total in seconds).\n# Output: count avg_s p50_s p99_s\nstats() {\n local file=\"$1\"\n if [[ ! -f \"$file\" ]] || [[ ! -s \"$file\" ]]; then\n echo \"0 0 0 0\"\n return\n fi\n sort -n \"$file\" > \"${file}.sorted\"\n local n\n n=$(wc -l < \"${file}.sorted\")\n if [[ \"$n\" -eq 0 ]]; then\n echo \"0 0 0 0\"\n return\n fi\n local avg p50 p99\n avg=$(awk '{s+=$1; c++} END { if(c>0) print s/c; else print 0 }' \"$file\")\n p50=$(awk -v n=\"$n\" 'NR==int(n*0.5+0.5){print $1; exit}' \"${file}.sorted\")\n p99=$(awk -v n=\"$n\" 'NR==int(n*0.99+0.5){print $1; exit}' \"${file}.sorted\")\n echo \"$n $avg $p50 $p99\"\n}\n\n# Run workload inside CONTAINER_NAME; /tmp/bench-domains.txt must already exist in container.\n# Usage: run_bench_to [limit] [rounds] [timeout]\nrun_bench_to() {\n local outfile=\"$1\"\n local limit=\"${2:-9999}\"\n local rounds=\"${3:-1}\"\n local use_timeout=\"${4:-}\"\n local cmd=(\n docker exec -e BENCH_TIMEOUT=\"${CURL_TIMEOUT}\" -e BENCH_OUTFILE=\"${outfile}\" -e BENCH_LIMIT=\"${limit}\" -e BENCH_ROUNDS=\"${rounds}\" \\\n \"${CONTAINER_NAME}\" sh -c '\n : > \"$BENCH_OUTFILE\"\n r=1\n while [ \"$r\" -le \"$BENCH_ROUNDS\" ]; do\n n=0\n while IFS= read -r url && [ \"$n\" -lt \"$BENCH_LIMIT\" ]; do\n ( curl -o /dev/null -s -I -w \"%{time_namelookup}\\t%{time_total}\\n\" --max-time \"$BENCH_TIMEOUT\" \"$url\" >> \"$BENCH_OUTFILE\" ) &\n n=$((n+1))\n done < /tmp/bench-domains.txt\n wait\n r=$((r+1))\n done\n '\n )\n if [[ \"$use_timeout\" == \"timeout\" ]] && command -v timeout >/dev/null 2>&1; then\n timeout \"${BENCH_EXEC_TIMEOUT}\" \"${cmd[@]}\"\n else\n \"${cmd[@]}\"\n fi\n}\n\n# Copy URL file into container (create temp file, docker cp, rm). Uses BENCH_DOMAINS.\ncopy_url_file_to_container() {\n local url_file=\"/tmp/bench-e2e-domains-$$.txt\"\n : > \"${url_file}\"\n for d in \"${BENCH_DOMAINS[@]}\"; do\n echo \"https://${d}\" >> \"${url_file}\"\n done\n docker cp \"${url_file}\" \"${CONTAINER_NAME}:/tmp/bench-domains.txt\"\n rm -f \"${url_file}\"\n}\n\n# Run warm-up + timed benchmark, collect timings. Writes /tmp/bench-e2e-{mode}-total.txt, -namelookup.txt, -wall.txt.\n# Requires: CONTAINER_NAME running, /tmp/bench-domains.txt inside container.\nrun_workload() {\n local mode=\"$1\"\n local out_total=\"/tmp/bench-e2e-${mode}-total.txt\"\n local out_namelookup=\"/tmp/bench-e2e-${mode}-namelookup.txt\"\n : > \"$out_total\"\n : > \"$out_namelookup\"\n\n local first_url=\"https://${BENCH_DOMAINS[0]}\"\n sleep 1\n # HEAD request: no response body, only check DNS + TCP + TLS + HTTP response.\n if ! docker exec \"${CONTAINER_NAME}\" curl -o /dev/null -s -I --max-time \"${CURL_TIMEOUT}\" \"${first_url}\"; then\n info \"Warm-up curl failed; stderr from one attempt:\"\n docker exec \"${CONTAINER_NAME}\" curl -o /dev/null -s -I --max-time 5 \"${first_url}\" 2>&1 || true\n return 1\n fi\n\n info \"Warm-up: first 10 domains, 1 round...\"\n bench_ret=0\n run_bench_to /tmp/bench-warmup.txt 10 1 2>/tmp/bench-e2e-stderr.txt || bench_ret=$?\n if [[ \"$bench_ret\" -ne 0 ]]; then\n info \"Warm-up run failed (exit $bench_ret); continuing with timed run anyway.\"\n fi\n\n info \"Running ${TOTAL_REQUESTS} E2E requests (${ROUNDS} rounds ร— ${NUM_DOMAINS} domains) inside container (max ${BENCH_EXEC_TIMEOUT}s)...\"\n local start_ts\n start_ts=$(date +%s.%N)\n bench_ret=0\n run_bench_to /tmp/bench-raw.txt 9999 \"${ROUNDS}\" timeout 2>/tmp/bench-e2e-stderr.txt || bench_ret=$?\n if [[ \"$bench_ret\" -ne 0 ]]; then\n info \"Benchmark run failed (exit $bench_ret) or hit timeout; using partial results if any.\"\n fi\n docker cp \"${CONTAINER_NAME}:/tmp/bench-raw.txt\" /tmp/bench-e2e-raw.txt 2>/dev/null || true\n local end_ts\n end_ts=$(date +%s.%N)\n\n if [[ -s /tmp/bench-e2e-stderr.txt ]]; then\n info \"docker exec stderr (first 10 lines):\"\n head -10 /tmp/bench-e2e-stderr.txt >&2\n fi\n if [[ ! -f /tmp/bench-e2e-raw.txt ]]; then\n : > /tmp/bench-e2e-raw.txt\n fi\n local lines\n lines=$(wc -l < /tmp/bench-e2e-raw.txt 2>/dev/null || echo 0)\n if [[ \"$lines\" -lt $((TOTAL_REQUESTS / 2)) ]]; then\n info \"WARN: only ${lines}/${TOTAL_REQUESTS} responses captured; curl may be failing inside container.\"\n fi\n\n awk -F'\\t' '{print $2}' /tmp/bench-e2e-raw.txt 2>/dev/null > \"$out_total\"\n awk -F'\\t' '{print $1}' /tmp/bench-e2e-raw.txt 2>/dev/null > \"$out_namelookup\"\n local wall_s\n wall_s=$(awk -v s=\"$start_ts\" -v e=\"$end_ts\" 'BEGIN { print e - s }')\n echo \"$wall_s\" > \"/tmp/bench-e2e-${mode}-wall.txt\"\n}\n\n# Run one benchmark phase: start container with given mode, push policy, run client workload, collect timings.\n# Usage: run_phase \"dns\" | \"dns+nft\"\nrun_phase() {\n local mode=\"$1\"\n info \"Phase: ${mode}\"\n cleanup\n mkdir -p \"${LOG_HOST_DIR}\"\n docker run -d --name \"${CONTAINER_NAME}\" \\\n --cap-add=NET_ADMIN \\\n --sysctl net.ipv6.conf.all.disable_ipv6=1 \\\n --sysctl net.ipv6.conf.default.disable_ipv6=1 \\\n -e OPENSANDBOX_EGRESS_MODE=\"${mode}\" \\\n -e OPENSANDBOX_LOG_OUTPUT=\"${LOG_CONTAINER_FILE}\" \\\n -v \"${LOG_HOST_DIR}:${LOG_CONTAINER_DIR}\" \\\n -p \"${POLICY_PORT}:18080\" \\\n \"${IMG}\"\n\n for i in $(seq 1 30); do\n if curl -sf \"http://127.0.0.1:${POLICY_PORT}/healthz\" >/dev/null 2>&1; then\n break\n fi\n sleep 0.5\n done\n\n local policy_egress=\"\"\n for d in \"${BENCH_DOMAINS[@]}\"; do\n policy_egress=\"${policy_egress}{\\\"action\\\":\\\"allow\\\",\\\"target\\\":\\\"${d}\\\"},\"\n done\n policy_egress=\"${policy_egress%,}\"\n local policy_json=\"{\\\"defaultAction\\\":\\\"deny\\\",\\\"egress\\\":[${policy_egress}]}\"\n curl -sf -XPOST \"http://127.0.0.1:${POLICY_PORT}/policy\" -d \"${policy_json}\" >/dev/null\n\n copy_url_file_to_container\n run_workload \"${mode}\"\n}\n\n# Run baseline phase: plain curl container, no egress container. Same workload for comparison.\nrun_phase_baseline() {\n info \"Phase: baseline (no egress)\"\n cleanup\n docker pull \"${BASELINE_IMG}\" > /dev/null 2>&1\n docker run -d --name \"${CONTAINER_NAME}\" \"${BASELINE_IMG}\" sleep 3600\n sleep 2\n copy_url_file_to_container\n run_workload \"baseline\"\n}\n\n# Print comparison table (baseline, dns, dns+nft)\nreport() {\n local nb n1 n2 avg0 avg1 avg2 p50_0 p50_1 p50_2 p99_0 p99_1 p99_2 wall0 wall1 wall2\n read -r nb avg0 p50_0 p99_0 <<< \"$(stats /tmp/bench-e2e-baseline-total.txt)\"\n read -r n1 avg1 p50_1 p99_1 <<< \"$(stats /tmp/bench-e2e-dns-total.txt)\"\n read -r n2 avg2 p50_2 p99_2 <<< \"$(stats /tmp/bench-e2e-dns+nft-total.txt)\"\n wall0=$(cat /tmp/bench-e2e-baseline-wall.txt 2>/dev/null || echo \"0\")\n wall1=$(cat /tmp/bench-e2e-dns-wall.txt 2>/dev/null || echo \"0\")\n wall2=$(cat /tmp/bench-e2e-dns+nft-wall.txt 2>/dev/null || echo \"0\")\n if [[ \"${nb:-0}\" -eq 0 ]] || [[ \"${n1:-0}\" -eq 0 ]] || [[ \"${n2:-0}\" -eq 0 ]]; then\n echo \"WARN: some phases had no successful requests; check container logs and network.\"\n fi\n\n local rps0 rps1 rps2\n rps0=$(awk -v n=\"$nb\" -v w=\"$wall0\" 'BEGIN { print (w>0 && n>0) ? n/w : 0 }')\n rps1=$(awk -v n=\"$n1\" -v w=\"$wall1\" 'BEGIN { print (w>0 && n>0) ? n/w : 0 }')\n rps2=$(awk -v n=\"$n2\" -v w=\"$wall2\" 'BEGIN { print (w>0 && n>0) ? n/w : 0 }')\n\n echo \"\"\n echo \"========== E2E benchmark: baseline vs dns vs dns+nft ==========\"\n echo \"Workload: ${TOTAL_REQUESTS} requests (${ROUNDS} rounds ร— ${NUM_DOMAINS} domains)\"\n echo \"\"\n local ov_avg1 ov_p50_1 ov_p99_1 ov_rps1 ov_avg2 ov_p50_2 ov_p99_2 ov_rps2\n ov_avg1=$(awk -v a=\"$avg1\" -v b=\"$avg0\" 'BEGIN { printf \"%+.1f\", (b>0 && b!=\"\") ? (a-b)/b*100 : 0 }')\n ov_p50_1=$(awk -v a=\"$p50_1\" -v b=\"$p50_0\" 'BEGIN { printf \"%+.1f\", (b>0 && b!=\"\") ? (a-b)/b*100 : 0 }')\n ov_p99_1=$(awk -v a=\"$p99_1\" -v b=\"$p99_0\" 'BEGIN { printf \"%+.1f\", (b>0 && b!=\"\") ? (a-b)/b*100 : 0 }')\n ov_rps1=$(awk -v a=\"$rps1\" -v b=\"$rps0\" 'BEGIN { printf \"%+.1f\", (b>0 && b!=\"\") ? (b-a)/b*100 : 0 }')\n ov_avg2=$(awk -v a=\"$avg2\" -v b=\"$avg0\" 'BEGIN { printf \"%+.1f\", (b>0 && b!=\"\") ? (a-b)/b*100 : 0 }')\n ov_p50_2=$(awk -v a=\"$p50_2\" -v b=\"$p50_0\" 'BEGIN { printf \"%+.1f\", (b>0 && b!=\"\") ? (a-b)/b*100 : 0 }')\n ov_p99_2=$(awk -v a=\"$p99_2\" -v b=\"$p99_0\" 'BEGIN { printf \"%+.1f\", (b>0 && b!=\"\") ? (a-b)/b*100 : 0 }')\n ov_rps2=$(awk -v a=\"$rps2\" -v b=\"$rps0\" 'BEGIN { printf \"%+.1f\", (b>0 && b!=\"\") ? (b-a)/b*100 : 0 }')\n\n printf \"%-10s %14s %20s %20s %20s\\n\" \"Mode\" \"Req/s\" \"Avg(s)\" \"P50(s)\" \"P99(s)\"\n printf \"%-10s %14s %20s %20s %20s\\n\" \"baseline\" \"$rps0\" \"$avg0\" \"$p50_0\" \"$p99_0\"\n printf \"%-10s %14s %20s %20s %20s\\n\" \"dns\" \"$(printf '%.2f(%s%%)' \"$rps1\" \"$ov_rps1\")\" \"$(printf '%.3f(%s%%)' \"$avg1\" \"$ov_avg1\")\" \"$(printf '%.3f(%s%%)' \"$p50_1\" \"$ov_p50_1\")\" \"$(printf '%.3f(%s%%)' \"$p99_1\" \"$ov_p99_1\")\"\n printf \"%-10s %14s %20s %20s %20s\\n\" \"dns+nft\" \"$(printf '%.2f(%s%%)' \"$rps2\" \"$ov_rps2\")\" \"$(printf '%.3f(%s%%)' \"$avg2\" \"$ov_avg2\")\" \"$(printf '%.3f(%s%%)' \"$p50_2\" \"$ov_p50_2\")\" \"$(printf '%.3f(%s%%)' \"$p99_2\" \"$ov_p99_2\")\"\n echo \"\"\n echo \"Overhead in parentheses vs baseline: latency +%% = slower, Req/s -%% = lower throughput.\"\n echo \"baseline: Plain container (${BASELINE_IMG}), no egress container.\"\n echo \"dns: DNS proxy only, no nft write (pass-through).\"\n echo \"dns+nft: DNS proxy + sync AddResolvedIPs before each DNS reply (L2 enforcement).\"\n echo \"\"\n echo \"Note: Warm-up runs before each phase. Baseline gives no-proxy comparison.\"\n echo \"==========\"\n}\n\ninfo \"Building image ${IMG}\"\ndocker build -t \"${IMG}\" -f \"${REPO_ROOT}/components/egress/Dockerfile\" \"${REPO_ROOT}\" > /dev/null 2>&1\n\nrun_phase_baseline\nrun_phase \"dns+nft\"\nrun_phase \"dns\"\nreport\ninfo \"Cleaning up\"\ncleanup\n" }, { "path": "components/egress/tests/egress-in-webhook.sh", "content": "#!/bin/bash\n\n# Copyright 2026 Alibaba Group Holding Ltd.\n# \n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n# \n# http://www.apache.org/licenses/LICENSE-2.0\n# \n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\ndocker run -d --name egress \\\n --rm \\\n --cap-add=NET_ADMIN \\\n --sysctl net.ipv6.conf.all.disable_ipv6=1 \\\n --sysctl net.ipv6.conf.default.disable_ipv6=1 \\\n -e OPENSANDBOX_EGRESS_MODE=dns+nft \\\n -e OPENSANDBOX_EGRESS_DENY_WEBHOOK=http://:8000 \\\n -e OPENSANDBOX_EGRESS_SANDBOX_ID=mytest \\\n -p 18080:18080 \\\n \"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:latest\"\n\n\nsleep 5\ncurl -sSf -XPOST \"http://127.0.0.1:18080/policy\" \\\n -d '{\"defaultAction\":\"allow\",\"egress\":[{\"action\":\"deny\",\"target\":\"*.github.com\"},{\"action\":\"deny\",\"target\":\"10.0.0.0/8\"}]}'" }, { "path": "components/egress/tests/hostname.txt", "content": "example.com\nexample.org\nexample.net\nexample.edu\nexample.io\ngithub.com\ngithub.io\ngoogle.com\ncloudflare.com\namazon.com\nwikipedia.org\nmozilla.org\napple.com\nmicrosoft.com\nyahoo.com\nfacebook.com\ntwitter.com\ninstagram.com\nlinkedin.com\nreddit.com\nstackoverflow.com\nnpmjs.com\npython.org\ngolang.org\nrust-lang.org\ndocker.com\nkubernetes.io\napache.org\ngnu.org\nkernel.org\nibm.com\noracle.com\nopenai.com\nanthropic.com\nstripe.com\nslack.com\ndropbox.com\nspotify.com\nnetflix.com\ntwitch.tv\ndiscord.com\nzoom.us\nmedium.com\nsubstack.com\nblogger.com\ntumblr.com\nimgur.com\nflickr.com\nvimeo.com\nsoundcloud.com\nbandcamp.com\npatreon.com\nkickstarter.com\netsy.com\nebay.com\ncraigslist.org\nalibaba.com\nbing.com\nduckduckgo.com\nbrave.com\nopera.com\nprotonmail.com\nfastmail.com\nzoho.com\nnotion.so\ntrello.com\nasana.com\natlassian.com\nbitbucket.org\ngitlab.com\nsourceforge.net\ncodepen.io\nvercel.com\nnetlify.com\nheroku.com\ndigitalocean.com\nlinode.com\nvultr.com\novh.com\nhetzner.com\nscaleway.com\narchlinux.org\ndebian.org\nubuntu.com\nfedoraproject.org\nopensuse.org\nfreebsd.org\nopenbsd.org\nmysql.com\nmongodb.com\nredis.io\nelastic.co\nnodejs.org\nreactjs.org\nvuejs.org\nsvelte.dev\nnextjs.org\nnuxtjs.org\njquery.com\nbootstrap.com\ntailwindcss.com\n" }, { "path": "components/egress/tests/smoke-dns.sh", "content": "#!/bin/bash\n\n# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n# Simple smoke test using local image.\n# Requires Docker with --cap-add=NET_ADMIN available.\n\nset -euo pipefail\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# tests/ is two levels under repo root: components/egress/tests -> climb 3 levels.\nREPO_ROOT=\"$(cd \"${SCRIPT_DIR}/../../..\" && pwd)\"\n\nIMG=\"opensandbox/egress:local\"\ncontainerName=\"egress-smoke-dns\"\nPOLICY_PORT=18080\n\ninfo() { echo \"[$(date +%H:%M:%S)] $*\"; }\n\ncleanup() {\n docker rm -f \"${containerName}\" >/dev/null 2>&1 || true\n}\ntrap cleanup EXIT\n\ninfo \"Building image ${IMG}\"\ndocker build -t \"${IMG}\" -f \"${REPO_ROOT}/components/egress/Dockerfile\" \"${REPO_ROOT}\"\n\ninfo \"Starting containerName\"\ndocker run -d --name \"${containerName}\" \\\n --cap-add=NET_ADMIN \\\n --sysctl net.ipv6.conf.all.disable_ipv6=1 \\\n --sysctl net.ipv6.conf.default.disable_ipv6=1 \\\n -e OPENSANDBOX_EGRESS_MODE=dns \\\n -p ${POLICY_PORT}:18080 \\\n \"${IMG}\"\n\ninfo \"Waiting for policy server...\"\nfor i in {1..50}; do\n if curl -sf \"http://127.0.0.1:${POLICY_PORT}/healthz\" >/dev/null; then\n break\n fi\n sleep 0.5\ndone\n\ninfo \"Pushing policy (allow by default; deny github.com & 10.0.0.0/8)\"\ncurl -sSf -XPOST \"http://127.0.0.1:${POLICY_PORT}/policy\" \\\n -d '{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"*.github.com\"}]}'\n\nrun_in_app() {\n docker run --rm --network container:\"${containerName}\" curlimages/curl \"$@\"\n}\n\npass() { info \"PASS: $*\"; }\nfail() { echo \"FAIL: $*\" >&2; exit 1; }\n\ninfo \"Test: denied domain should fail (google.com)\"\nif run_in_app -I https://google.com --max-time 5 >/dev/null 2>&1; then\n fail \"google.com should be blocked\"\nelse\n pass \"google.com blocked\"\nfi\n\ninfo \"Test: allowed domain should succeed (api.github.com)\"\nrun_in_app -I https://api.github.com --max-time 10 >/dev/null 2>&1 || fail \"api.github.com should succeed\"\npass \"api.github.com allowed\"\n\ninfo \"All smoke tests passed.\"" }, { "path": "components/egress/tests/smoke-dynamic-ip.sh", "content": "#!/bin/bash\n\n# Copyright 2026 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n# Smoke test: default deny + domain allow in dns+nft mode.\n# Verifies that allowing a domain causes its resolved IP to be added to nft (dynamic IP),\n# so that curl to that domain succeeds without static IP/CIDR in policy.\n\nset -euo pipefail\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# tests/ is two levels under repo root: components/egress/tests -> climb 3 levels.\nREPO_ROOT=\"$(cd \"${SCRIPT_DIR}/../../..\" && pwd)\"\n\nIMG=\"opensandbox/egress:local\"\ncontainerName=\"egress-smoke-dynamic-ip\"\nPOLICY_PORT=18080\n\ninfo() { echo \"[$(date +%H:%M:%S)] $*\"; }\n\ncleanup() {\n docker rm -f \"${containerName}\" >/dev/null 2>&1 || true\n}\ntrap cleanup EXIT\n\ninfo \"Building image ${IMG}\"\ndocker build -t \"${IMG}\" -f \"${REPO_ROOT}/components/egress/Dockerfile\" \"${REPO_ROOT}\"\n\ninfo \"Starting sidecar (dns+nft)\"\ndocker run -d --name \"${containerName}\" \\\n --cap-add=NET_ADMIN \\\n --sysctl net.ipv6.conf.all.disable_ipv6=1 \\\n --sysctl net.ipv6.conf.default.disable_ipv6=1 \\\n -e OPENSANDBOX_EGRESS_MODE=dns+nft \\\n -p ${POLICY_PORT}:18080 \\\n \"${IMG}\"\n\ninfo \"Waiting for policy server...\"\nfor i in $(seq 1 50); do\n if curl -sf \"http://127.0.0.1:${POLICY_PORT}/healthz\" >/dev/null; then\n break\n fi\n sleep 0.5\ndone\n\ninfo \"Pushing policy (default deny; allow google.com only)\"\ncurl -sSf -XPOST \"http://127.0.0.1:${POLICY_PORT}/policy\" \\\n -d '{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"google.com\"}]}'\n\nrun_in_app() {\n docker run --rm --network container:\"${containerName}\" curlimages/curl \"$@\"\n}\n\npass() { info \"PASS: $*\"; }\nfail() { echo \"FAIL: $*\" >&2; exit 1; }\n\ninfo \"Test: allowed domain (google.com) should succeed via dynamic IP\"\nrun_in_app -I https://google.com --max-time 15 >/dev/null 2>&1 || fail \"google.com should succeed (DNS allow + dynamic IP in nft)\"\npass \"google.com allowed\"\n\ninfo \"Test: denied domain (api.github.com) should fail\"\nif run_in_app -I https://api.github.com --max-time 8 >/dev/null 2>&1; then\n fail \"api.github.com should be blocked\"\nelse\n pass \"api.github.com blocked\"\nfi\n\ninfo \"Test: denied IP (1.1.1.1) should fail\"\nif run_in_app -I 1.1.1.1 --max-time 8 >/dev/null 2>&1; then\n fail \"1.1.1.1 should be blocked\"\nelse\n pass \"1.1.1.1 blocked\"\nfi\n\ninfo \"All smoke tests (dynamic IP) passed.\"\n" }, { "path": "components/egress/tests/smoke-nft.sh", "content": "#!/bin/bash\n\n# Copyright 2026 Alibaba Group Holding Ltd.\n# \n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n# \n# http://www.apache.org/licenses/LICENSE-2.0\n# \n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n# Simple smoke test using local image.\n# Requires Docker with --cap-add=NET_ADMIN available.\n\nset -euo pipefail\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\n# tests/ is two levels under repo root: components/egress/tests -> climb 3 levels.\nREPO_ROOT=\"$(cd \"${SCRIPT_DIR}/../../..\" && pwd)\"\n\nIMG=\"opensandbox/egress:local\"\ncontainerName=\"egress-smoke-nft\"\nPOLICY_PORT=18080\n\ninfo() { echo \"[$(date +%H:%M:%S)] $*\"; }\n\ncleanup() {\n docker rm -f \"${containerName}\" >/dev/null 2>&1 || true\n}\ntrap cleanup EXIT\n\ninfo \"Building image ${IMG}\"\ndocker build -t \"${IMG}\" -f \"${REPO_ROOT}/components/egress/Dockerfile\" \"${REPO_ROOT}\"\n\ninfo \"Starting containerName\"\ndocker run -d --name \"${containerName}\" \\\n --cap-add=NET_ADMIN \\\n --sysctl net.ipv6.conf.all.disable_ipv6=1 \\\n --sysctl net.ipv6.conf.default.disable_ipv6=1 \\\n -e OPENSANDBOX_EGRESS_MODE=dns+nft \\\n -p ${POLICY_PORT}:18080 \\\n \"${IMG}\"\n\ninfo \"Waiting for policy server...\"\nfor i in {1..50}; do\n if curl -sf \"http://127.0.0.1:${POLICY_PORT}/healthz\" >/dev/null; then\n break\n fi\n sleep 0.5\ndone\n\ninfo \"Pushing policy (allow by default; deny github.com & 10.0.0.0/8)\"\ncurl -sSf -XPOST \"http://127.0.0.1:${POLICY_PORT}/policy\" \\\n -d '{\"defaultAction\":\"allow\",\"egress\":[{\"action\":\"deny\",\"target\":\"*.github.com\"},{\"action\":\"deny\",\"target\":\"10.0.0.0/8\"}]}'\n\nrun_in_app() {\n docker run --rm --network container:\"${containerName}\" curlimages/curl \"$@\"\n}\n\npass() { info \"PASS: $*\"; }\nfail() { echo \"FAIL: $*\" >&2; exit 1; }\n\ninfo \"Test: allowed domain should succeed (google.com)\"\nrun_in_app -I https://google.com --max-time 10 >/dev/null 2>&1 || fail \"google.com should succeed\"\npass \"google.com allowed\"\n\ninfo \"Test: denied domain should fail (api.github.com)\"\nif run_in_app -I https://api.github.com --max-time 8 >/dev/null 2>&1; then\n fail \"api.github.com should be blocked\"\nelse\n pass \"api.github.com blocked\"\nfi\n\ninfo \"Test: allowed IP should succeed (1.1.1.1)\"\nrun_in_app -I https://1.1.1.1 --max-time 10 >/dev/null 2>&1 || fail \"1.1.1.1 should succeed\"\npass \"1.1.1.1 allowed\"\n\ninfo \"Test: denied CIDR should fail (10.0.0.1)\"\nif run_in_app -I http://10.0.0.1 --max-time 5 >/dev/null 2>&1; then\n fail \"10.0.0.1 should be blocked\"\nelse\n pass \"10.0.0.1 blocked\"\nfi\n\ninfo \"Test: DoT (853) should be blocked\"\nif run_in_app -k https://1.1.1.1:853 --max-time 5 >/dev/null 2>&1; then\n fail \"DoT 853 should be blocked\"\nelse\n pass \"DoT 853 blocked\"\nfi\n\ninfo \"Rules update: wildcard deny -> patch allow specific (dns+nft)\"\ncurl -sSf -XPOST \"http://127.0.0.1:${POLICY_PORT}/policy\" \\\n -d '{\"defaultAction\":\"allow\",\"egress\":[{\"action\":\"deny\",\"target\":\"*.cloudflare.com\"}]}'\n\ninfo \"Test: www.cloudflare.com should be blocked initially (deny via wildcard)\"\nif run_in_app -I https://www.cloudflare.com --max-time 8 >/dev/null 2>&1; then\n fail \"www.cloudflare.com should be blocked before patch\"\nelse\n pass \"www.cloudflare.com blocked before patch\"\nfi\n\ninfo \"Patching allow for www.cloudflare.com (specific should override earlier deny)\"\ncurl -sSf -XPATCH \"http://127.0.0.1:${POLICY_PORT}/policy\" \\\n -d '[{\"action\":\"allow\",\"target\":\"www.cloudflare.com\"}]'\n\ninfo \"Test: www.cloudflare.com should be allowed after patch\"\nrun_in_app -I https://www.cloudflare.com --max-time 10 >/dev/null 2>&1 || fail \"www.cloudflare.com should succeed after patch\"\npass \"www.cloudflare.com allowed after patch\"\n\ninfo \"Rules update: wildcard allow -> patch deny specific (dns+nft)\"\ncurl -sSf -XPOST \"http://127.0.0.1:${POLICY_PORT}/policy\" \\\n -d '{\"defaultAction\":\"deny\",\"egress\":[{\"action\":\"allow\",\"target\":\"*.mozilla.org\"}]}'\n\ninfo \"Test: www.mozilla.org should be allowed initially (allow via wildcard)\"\nrun_in_app -I https://www.mozilla.org --max-time 10 >/dev/null 2>&1 || fail \"www.mozilla.org should succeed before patch\"\npass \"www.mozilla.org allowed before patch\"\n\ninfo \"Patching deny for www.mozilla.org (specific should override earlier allow)\"\ncurl -sSf -XPATCH \"http://127.0.0.1:${POLICY_PORT}/policy\" \\\n -d '[{\"action\":\"deny\",\"target\":\"www.mozilla.org\"}]'\n\ninfo \"Test: www.mozilla.org should be blocked after patch\"\nif run_in_app -I https://www.mozilla.org --max-time 8 >/dev/null 2>&1; then\n fail \"www.mozilla.org should be blocked after patch\"\nelse\n pass \"www.mozilla.org blocked after patch\"\nfi\n\ninfo \"All smoke tests passed.\"" }, { "path": "components/egress/tests/webhook-server.py", "content": "#!/usr/bin/env python3\n\n# Copyright 2026 Alibaba Group Holding Ltd.\n# \n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n# \n# http://www.apache.org/licenses/LICENSE-2.0\n# \n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"\nLightweight HTTP server to receive OPENSANDBOX_EGRESS_DENY_WEBHOOK callbacks.\n\nConfig:\n- WEBHOOK_HOST: listen address (default 0.0.0.0)\n- WEBHOOK_PORT: listen port (default 8000)\n- WEBHOOK_PATH: webhook path (default /)\n\nRun:\n python webhook_server.py\nThen point OPENSANDBOX_EGRESS_DENY_WEBHOOK to http://:\n\"\"\"\n\nimport http.server\nimport json\nimport os\nimport socketserver\nfrom datetime import datetime\n\nHOST = os.getenv(\"WEBHOOK_HOST\", \"0.0.0.0\")\nPORT = int(os.getenv(\"WEBHOOK_PORT\", \"8000\"))\nPATH = os.getenv(\"WEBHOOK_PATH\", \"/\")\n\n\nclass WebhookHandler(http.server.BaseHTTPRequestHandler):\n def _send(self, code: int = 200, body: str = \"ok\") -> None:\n self.send_response(code)\n self.send_header(\"Content-Type\", \"text/plain; charset=utf-8\")\n self.end_headers()\n self.wfile.write(body.encode(\"utf-8\"))\n\n def do_POST(self) -> None: # noqa: N802 (BaseHTTPRequestHandler API)\n # Only allow the configured path\n if self.path != PATH:\n self._send(404, \"not found\")\n return\n\n length = int(self.headers.get(\"Content-Length\", 0))\n raw = self.rfile.read(length) if length else b\"\"\n\n payload = raw.decode(\"utf-8\", errors=\"replace\")\n try:\n parsed = json.loads(payload)\n except json.JSONDecodeError:\n parsed = None\n\n # Log request info for debugging\n print(f\"\\n[{datetime.utcnow().isoformat()}Z] Received webhook\")\n print(f\"Path: {self.path}\")\n print(f\"Headers: {dict(self.headers)}\")\n print(f\"Raw body: {payload}\")\n if parsed is not None:\n print(\"Parsed JSON:\")\n print(json.dumps(parsed, indent=2))\n\n self._send(200, \"received\")\n\n # Silence default logging to reduce noise\n def log_message(self, *args) -> None:\n return\n\n\ndef main() -> None:\n with socketserver.TCPServer((HOST, PORT), WebhookHandler) as httpd:\n print(f\"Listening on http://{HOST}:{PORT}{PATH} ...\")\n httpd.serve_forever()\n\n\nif __name__ == \"__main__\":\n main()" }, { "path": "components/execd/.golangci.yml", "content": "run:\n skip-dirs:\n - vendor\n - tests\n - scripts\n skip-files:\n - .*/zz_generated.deepcopy.go\n - .*/mock/*.go\n tests: false\n timeout: 10m\nlinters-settings:\n funlen:\n lines: 500\n statements: 200\n gocyclo:\n min-complexity: 40\n gosimple:\n checks: [\"S1019\", \"S1002\"]\n staticcheck:\n checks: [\"SA4006\"]\n govet:\n enable:\n - asmdecl\n - assign\n - atomic\n - atomicalign\n - bools\n - buildtag\n - cgocall\n - copylocks\n - deepequalerrors\n - errorsas\n - findcall\n - framepointer\n - httpresponse\n - ifaceassert\n - lostcancel\n - nilfunc\n - nilness\n - reflectvaluecompare\n - shift\n - sigchanyzer\n - sortslice\n - stdmethods\n - stringintconv\n - testinggoroutine\n - tests\n - unmarshal\n - unreachable\n - unsafeptr\n - unusedresult\n - printf\n disable:\n - composites\n - loopclosure\n - fieldalignment\n - shadow\n - structtag\n - unusedwrite\n errcheck:\n exclude-functions:\n - flag.Set\n - os.Setenv\n - os.Unsetenv\n - logger.Sync\n - fmt.Fprintf\n - fmt.Fprintln\n - (io.Closer).Close\n - (io.ReadCloser).Close\n - (k8s.io/client-go/tools/cache.SharedInformer).AddEventHandler\n nestif:\n min-complexity: 32\n goconst:\n # Minimal length of string constant.\n # Default: 3\n min-len: 3\n # Minimum occurrences of constant string count to trigger issue.\n # Default: 3\n min-occurrences: 3\n # Ignore test files.\n # Default: false\n ignore-tests: true\n match-constant: false\n numbers: true\n min: 2\n max: 10\n ignore-calls: true\n gosec:\n includes:\n - G101 # Look for hard coded credentials\n - G102 # Bind to all interfaces\n - G103 # Audit the use of unsafe block\n - G104 # Audit errors not checked\n - G106 # Audit the use of ssh.InsecureIgnoreHostKey\n - G107 # Url provided to HTTP request as taint input\n - G108 # Profiling endpoint automatically exposed on /debug/pprof\n - G109 # Potential Integer overflow made by strconv.Atoi result conversion to int16/32\n - G110 # Potential DoS vulnerability via decompression bomb\n - G111 # Potential directory traversal\n - G112 # Potential slowloris attack\n - G113 # Usage of Rat.SetString in math/big with an overflow (CVE-2022-23772)\n # - G114 # Use of net/http serve function that has no support for setting timeouts\n - G201 # SQL query construction using format string\n - G202 # SQL query construction using string concatenation\n - G203 # Use of unescaped data in HTML templates\n #- G204 # Audit use of command execution\n - G301 # Poor file permissions used when creating a directory\n - G302 # Poor file permissions used with chmod\n - G303 # Creating tempfile using a predictable path\n - G304 # File path provided as taint input\n - G305 # File traversal when extracting zip/tar archive\n - G306 # Poor file permissions used when writing to a new file\n - G307 # Deferring a method which returns an error\n #- G401 # Detect the usage of DES, RC4, MD5 or SHA1\n - G402 # Look for bad TLS connection settings\n - G403 # Ensure minimum RSA key length of 2048 bits\n - G404 # Insecure random number source (rand)\n #- G501 # Import blocklist: crypto/md5\n - G502 # Import blocklist: crypto/des\n - G503 # Import blocklist: crypto/rc4\n - G504 # Import blocklist: net/http/cgi\n - G505 # Import blocklist: crypto/sha1\n - G601 # Implicit memory aliasing of items from a range statement\n # Exclude generated files\n # Default: false\n exclude-generated: true\n # Filter out the issues with a lower severity than the given value.\n # Valid options are: low, medium, high.\n # Default: low\n severity: medium\n # Filter out the issues with a lower confidence than the given value.\n # Valid options are: low, medium, high.\n # Default: low\n confidence: medium\n # Concurrency value.\n # Default: the number of logical CPUs usable by the current process.\n concurrency: 12\n # To specify the configuration of rules.\n config:\n # Globals are applicable to all rules.\n global:\n nosec: true\n show-ignored: true\n audit: true\n G101:\n # Regexp pattern for variables and constants to find.\n # Default: \"(?i)passwd|pass|password|pwd|secret|token|pw|apiKey|bearer|cred\"\n pattern: \"(?i)example\"\n # If true, complain about all cases (even with low entropy).\n # Default: false\n ignore_entropy: false\n # Maximum allowed entropy of the string.\n # Default: \"80.0\"\n entropy_threshold: \"80.0\"\n per_char_threshold: \"3.0\"\n truncate: \"32\"\n G104:\n fmt:\n - Fscanf\n G111:\n # Regexp pattern to find potential directory traversal.\n # Default: \"http\\\\.Dir\\\\(\\\"\\\\/\\\"\\\\)|http\\\\.Dir\\\\('\\\\/'\\\\)\"\n pattern: \"custom\\\\.Dir\\\\(\\\\)\"\n # Maximum allowed permissions mode for os.Mkdir and os.MkdirAll\n # Default: \"0750\"\n G301: \"0750\"\n # Maximum allowed permissions mode for os.OpenFile and os.Chmod\n # Default: \"0600\"\n G302: \"0600\"\n # Maximum allowed permissions mode for os.WriteFile and ioutil.WriteFile\n # Default: \"0600\"\n G306: \"0600\"\n nilnil:\n checked-types:\n - ptr\n - map\n - chan\n depguard:\n rules:\n prevent_unmaintained_packages:\n list-mode: lax # allow unless explicitely denied\n files:\n - $all\n - \"!$test\"\n allow:\n - $gostd\n - path/filepath\n deny:\n - pkg: io/ioutil\n desc: \"replaced by io and os packages since Go 1.16: https://tip.golang.org/doc/go1.16#ioutil\"\n - pkg: path\n desc: \"replaced by cross-platform package path/filepath\"\n gci:\n # Section configuration to compare against.\n # Section names are case-insensitive and may contain parameters in ().\n # The default order of sections is `standard > default > custom > blank > dot > alias > localmodule`,\n # If `custom-order` is `true`, it follows the order of `sections` option.\n # Default: [\"standard\", \"default\"]\n sections:\n - standard # Standard section: captures all standard packages.\n - default # Default section: contains all imports that could not be matched to another section type.:\n - prefix(github.com/org/project) # Custom section: groups all imports with the specified Prefix.\n - blank # Blank section: contains all blank imports. This section is not present unless explicitly enabled.\n - dot # Dot section: contains all dot imports. This section is not present unless explicitly enabled.\n - localmodule # Local module section: contains all local packages. This section is not present unless explicitly enabled.\n # Skip generated files.\n # Default: true\n skip-generated: true\n # Enable custom order of sections.\n # If `true`, make the section order the same as the order of `sections`.\n # Default: false\n custom-order: true\n # Drops lexical ordering for custom sections.\n # Default: false\n no-lex-order: true\n forbidigo:\n forbid:\n # Forbid spew Dump, whether it is called as function or method.\n # Depends on analyze-types below.\n - ^spew\\.(ConfigState\\.)?Dump$\n # The package name might be ambiguous.\n # The full import path can be used as additional criteria.\n # Depends on analyze-types below.\n - p: ^v1.Dump$\n pkg: ^example.com/pkg/api/v1$\n\nlinters:\n enable:\n - asasalint\n - asciicheck\n - bidichk\n - bodyclose\n # - cyclop\n - decorder\n - depguard\n - errcheck\n # - errchkjson\n - errorlint\n - forbidigo\n # - forcetypeassert\n - funlen\n - ineffassign\n - gocognit\n - gocyclo\n - goheader\n - gomodguard\n - goprintffuncname\n - gosimple\n - gosec\n - grouper\n - importas\n - maintidx\n - misspell\n - nakedret\n - nilerr\n - nilnil\n # - noctx\n - nosprintfhostport\n - paralleltest\n - predeclared\n # - promlinter\n - reassign\n - sqlclosecheck\n - staticcheck\n - tenv\n - testpackage\n - tparallel\n # del\n # - typecheck\n - usestdlibvars\n - nestif\n - unused\n - makezero\n - govet\n - goconst\n - gci\n # - rowserrcheck\n # 1.59 version no new lints\n # 1.58 version new lints\n # - fatcontext\n - canonicalheader\n # 1.57 version new lints\n - copyloopvar\n - intrange\n # 1.56 version new lints\n - spancheck\n # 1.55 version new lints\n - gochecksumtype\n - perfsprint\n - sloglint\n - testifylint\n - mirror\n - zerologlint\n # 1.51 version new lints\n - gocheckcompilerdirectives\n # 1.50 version new lints\n - testableexamples\n\nissues:\n # Note: path identifiers are regular expressions, hence the \\.go suffixes.\n exclude-rules:\n - path: main\\.go\n linters:\n - forbidigo\n - path: _test\\.go\n linters:\n - dogsled\n - errcheck\n - goconst\n - gosec\n - ineffassign\n - maintidx\n - typecheck\n - path: \\.go$\n text: \"should have a package comment\"\n - path: \\.go$\n text: 'exported (.+) should have comment( \\(or a comment on this block\\))? or be unexported'\n - path: \\.go$\n text: \"fmt.Sprintf can be replaced with string concatenation\"\n" }, { "path": "components/execd/DEVELOPMENT.md", "content": "# Development Guide - execd\n\nThis comprehensive guide explains how to work on `execd` as a contributor or maintainer. It covers environment setup,\ndevelopment workflows, testing strategies, architectural patterns, and subsystem-specific implementation details.\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n- [Project Structure](#project-structure)\n- [Coding Standards](#coding-standards)\n- [Testing Strategy](#testing-strategy)\n- [Subsystem Guides](#subsystem-guides)\n- [Common Development Tasks](#common-development-tasks)\n- [Debugging Techniques](#debugging-techniques)\n- [Performance Optimization](#performance-optimization)\n- [Contributing Guidelines](#contributing-guidelines)\n- [Additional Resources](#additional-resources)\n\n## Getting Started\n\n### Prerequisites\n\n#### Required Tools\n\n- **Go 1.24+** - Match the version declared in `go.mod`\n- **Git** - Version control\n- **Make** - Build automation (optional but recommended)\n\n#### Optional but Recommended\n\n- **golangci-lint** - For comprehensive linting\n- **Docker/Podman** - For containerized testing and deployment\n- **Jupyter Server** - Required for integration tests with real kernels\n- **VS Code/GoLand** - IDE with Go support\n\n### Initial Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/alibaba/OpenSandbox.git\ncd OpenSandbox/components/execd\n\n# Download dependencies\ngo mod download\n\n# Verify setup\ngo build -o bin/execd .\n```\n\n## Project Structure\n\n### Project Structure Deep Dive\n\n```\nexecd/\nโ”œโ”€โ”€ main.go # Application entry point\nโ”œโ”€โ”€ go.mod # Go module definition\nโ”œโ”€โ”€ Makefile # Build automation\nโ”œโ”€โ”€ Dockerfile # Container image definition\nโ”‚\nโ”œโ”€โ”€ pkg/ # Public packages\nโ”‚ โ”œโ”€โ”€ flag/ # CLI flag parsing\nโ”‚ โ”œโ”€โ”€ web/ # HTTP layer\nโ”‚ โ”‚ โ”œโ”€โ”€ router.go # Route registration\nโ”‚ โ”‚ โ”œโ”€โ”€ controller/ # Request handlers\nโ”‚ โ”‚ โ””โ”€โ”€ model/ # API models\nโ”‚ โ”œโ”€โ”€ runtime/ # Execution engine\nโ”‚ โ”‚ โ”œโ”€โ”€ ctrl.go # Main controller\nโ”‚ โ”‚ โ”œโ”€โ”€ jupyter.go # Jupyter execution\nโ”‚ โ”‚ โ””โ”€โ”€ command.go # Shell command execution\nโ”‚ โ”œโ”€โ”€ jupyter/ # Jupyter client\nโ”‚ โ”‚ โ”œโ”€โ”€ client.go # HTTP/WebSocket client\nโ”‚ โ”‚ โ”œโ”€โ”€ session/ # Session management\nโ”‚ โ”‚ โ””โ”€โ”€ execute/ # Execution protocol\nโ”‚ โ””โ”€โ”€ util/ # Utilities\nโ”‚\nโ””โ”€โ”€ tests/ # Integration test scripts\n```\n\n### Key Design Patterns\n\n#### 1. Controller Pattern (pkg/web/controller)\n\nControllers are thin HTTP handlers that parse requests, validate, delegate to runtime, and stream responses via SSE.\n\n#### 2. Runtime Controller Pattern (pkg/runtime)\n\nThe runtime controller dispatches requests to appropriate executors (Jupyter, Command, SQL) and manages session\nlifecycle.\n\n#### 3. Hook Pattern for Streaming\n\nExecution results are streamed via hooks, allowing controllers to transform runtime events into SSE events without tight\ncoupling.\n\n## Coding Standards\n\n### Go Conventions\n\n#### Formatting\n\n**Always use `gofmt`** before committing:\n\n```bash\ngofmt -w .\n# or\nmake fmt\n```\n\n#### Import Organization\n\nThree groups separated by blank lines:\n\n```go\nimport (\n // Standard library\n \"context\"\n \"fmt\"\n\n // Third-party\n \"github.com/beego/beego/v2/core/logs\"\n\n // Internal\n \"github.com/alibaba/opensandbox/execd/pkg/runtime\"\n)\n```\n\n#### Error Handling\n\nAlways handle errors explicitly:\n\n```go\n// Good\nresult, err := someOperation()\nif err != nil {\n logs.Error(\"operation failed: %v\", err)\n return fmt.Errorf(\"failed to do something: %w\", err)\n}\n\n// Bad - silent failure\nresult, _ := someOperation()\n```\n\n#### Logging\n\nUse Beego's structured logger:\n\n```go\nlogs.Info(\"starting execution: sessionID=%s\", sessionID)\nlogs.Warning(\"session busy: sessionID=%s\", sessionID)\nlogs.Error(\"execution failed: error=%v\", err)\nlogs.Debug(\"received event: type=%s\", eventType)\n```\n\n### Concurrency Best Practices\n\n#### Use safego for goroutines\n\nAlways use `safego.Go` to prevent panics:\n\n```go\nimport \"github.com/alibaba/opensandbox/execd/pkg/util/safego\"\n\nsafego.Go(func() {\n processInBackground()\n})\n```\n\n#### Context Propagation\n\nAlways respect context cancellation:\n\n```go\nfunc (c *Controller) runCommand(ctx context.Context, req *ExecuteCodeRequest) error {\n cmd := exec.CommandContext(ctx, \"bash\", \"-c\", req.Code)\n\n go func() {\n <-ctx.Done()\n if cmd.Process != nil {\n cmd.Process.Kill()\n }\n }()\n\n return cmd.Run()\n}\n```\n\n## Testing Strategy\n\n### Unit Tests\n\nLocated in `*_test.go` files alongside source code.\n\n**Example:**\n\n```go\nfunc TestController_Execute_Python(t *testing.T) {\n ctrl := NewController(\"http://jupyter:8888\", \"test-token\")\n\n req := &ExecuteCodeRequest{\n Language: Python,\n Code: \"print('hello')\",\n }\n\n err := ctrl.Execute(req)\n assert.NoError(t, err)\n}\n```\n\n**Running Unit Tests:**\n\n```bash\ngo test ./pkg/...\n# with coverage\ngo test -v -cover ./pkg/...\n```\n\n### Integration Tests\n\nLocated in `*_integration_test.go`, require real dependencies.\n\n**Running Integration Tests:**\n\n```bash\nexport JUPYTER_URL=http://localhost:8888\nexport JUPYTER_TOKEN=your-token\ngo test -v ./pkg/jupyter/...\n```\n\n### Test Coverage\n\nCheck coverage:\n\n```bash\ngo test -coverprofile=coverage.out ./pkg/...\ngo tool cover -html=coverage.out -o coverage.html\n```\n\n**Coverage Goals:**\n\n- Core packages (`pkg/runtime`, `pkg/jupyter`): > 80%\n- Controllers (`pkg/web/controller`): > 70%\n- Utilities (`pkg/util`): > 90%\n\n## Subsystem Guides\n\n### Working with Jupyter Integration\n\n#### Architecture\n\n```\npkg/jupyter/\nโ”œโ”€โ”€ client.go # Main client\nโ”œโ”€โ”€ transport.go # Connection handling\nโ”œโ”€โ”€ session/ # Session lifecycle\nโ”œโ”€โ”€ execute/ # Execution protocol\nโ””โ”€โ”€ auth/ # Authentication\n```\n\n#### Adding New Kernel Support\n\n1. Define language in `pkg/runtime/language.go`:\n\n```go\nconst Ruby Language = \"ruby\"\n```\n\n2. Map to kernel in `pkg/runtime/jupyter.go`\n\n3. Test with real kernel:\n\n```bash\n# Install Ruby kernel\ngem install iruby\niruby register --force\n\n# Run test\nexport JUPYTER_URL=http://localhost:8888\ngo test -v ./pkg/jupyter/integration_test.go\n```\n\n#### Debugging Jupyter Communication\n\nRun debug integration test:\n\n```bash\ngo test -v ./pkg/jupyter/debug_integration_test.go\n```\n\nThis dumps complete HTTP request/response pairs.\n\n### Working with Command Execution\n\n#### Key Implementation Details\n\n**Process Group Management:**\n\n```go\ncmd.SysProcAttr = &syscall.SysProcAttr{\n Setpgid: true, // Create new process group\n}\n```\n\nThis allows signal forwarding to all child processes:\n\n```go\nsyscall.Kill(-cmd.Process.Pid, syscall.SIGTERM)\n```\n\n**Signal Forwarding:**\n\n```go\nsignals := make(chan os.Signal, 1)\nsignal.Notify(signals)\n\ngo func() {\n for sig := range signals {\n if sig != syscall.SIGCHLD && sig != syscall.SIGURG {\n syscall.Kill(-cmd.Process.Pid, sig.(syscall.Signal))\n }\n }\n}()\n```\n\n**Stdout/Stderr Streaming:**\n\nCommands write to temporary log files, which are tailed and streamed to hooks.\n\n## Common Development Tasks\n\n### Adding a New API Endpoint\n\n1. **Define model** in `pkg/web/model/`:\n\n```go\ntype NewFeatureRequest struct {\n Param1 string `json:\"param1\" validate:\"required\"`\n Param2 int `json:\"param2\"`\n}\n```\n\n2. **Add controller method** in `pkg/web/controller/`:\n\n```go\nfunc (c *MyController) NewFeature() {\n var req model.NewFeatureRequest\n json.Unmarshal(c.Ctx.Input.RequestBody, &req)\n\n // Business logic\n result := processNewFeature(req)\n\n c.Data[\"json\"] = result\n c.ServeJSON()\n}\n```\n\n3. **Register route** in `pkg/web/router.go`:\n\n```go\nmyNamespace := web.NewNamespace(\"/my-feature\",\n web.NSRouter(\"\", &controller.MyController{}, \"post:NewFeature\"),\n)\nweb.AddNamespace(myNamespace)\n```\n\n### Adding Configuration Flag\n\n1. **Declare in `pkg/flag/flags.go`:**\n\n```go\nvar NewFeatureTimeout time.Duration\n```\n\n2. **Parse in `pkg/flag/parser.go`:**\n\n```go\nfunc InitFlags() {\n flag.DurationVar(&NewFeatureTimeout, \"new-feature-timeout\", 30*time.Second, \"Description\")\n\n // Parse environment variable\n if env := os.Getenv(\"NEW_FEATURE_TIMEOUT\"); env != \"\" {\n if d, err := time.ParseDuration(env); err == nil {\n NewFeatureTimeout = d\n }\n }\n\n flag.Parse()\n}\n```\n\n3. **Update README** with new flag documentation\n\n## Debugging Techniques\n\n### Local Debugging with Delve\n\n```bash\n# Install delve\ngo install github.com/go-delve/delve/cmd/dlv@latest\n\n# Start debugging\ndlv debug . -- \\\n --jupyter-host=http://localhost:8888 \\\n --jupyter-token=test\n\n# Set breakpoint\n(dlv) break pkg/runtime/ctrl.go:57\n(dlv) continue\n```\n\n### Debugging SSE Streams\n\n**Test with curl:**\n\n```bash\ncurl -N -H \"x-access-token: dev\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"language\":\"python\",\"code\":\"print(\\\"test\\\")\"}' \\\n http://localhost:44772/code\n```\n\nThe `-N` flag disables buffering for real-time events.\n\n**Debug in browser:**\n\n```javascript\nconst eventSource = new EventSource('/code');\n\neventSource.addEventListener('stdout', (e) => {\n console.log('stdout:', e.data);\n});\n\neventSource.addEventListener('error', (e) => {\n console.error('error:', e.data);\n});\n```\n\n### Performance Profiling\n\n**CPU Profile:**\n\n```bash\n# Add to main.go\nimport _ \"net/http/pprof\"\n\ngo func() {\n http.ListenAndServe(\"localhost:6060\", nil)\n}()\n\n# Collect profile\ngo tool pprof http://localhost:6060/debug/pprof/profile?seconds=30\n```\n\n**Memory Profile:**\n\n```bash\ngo tool pprof http://localhost:6060/debug/pprof/heap\n```\n\n**Goroutine Inspection:**\n\n```bash\ncurl http://localhost:6060/debug/pprof/goroutine?debug=2\n```\n\n## Performance Optimization\n\n### Optimization Guidelines\n\n1. **Profile before optimizing** - Use pprof to identify bottlenecks\n2. **Benchmark changes** - Measure impact of optimizations\n3. **Use `sync.Pool`** for frequently allocated objects\n4. **Minimize allocations** in hot paths\n5. **Buffer channels** appropriately\n\n### Example: Optimizing SSE Writer\n\n**Before:**\n\n```go\nfunc writeEvent(w http.ResponseWriter, event, data string) {\n fmt.Fprintf(w, \"event: %s\\ndata: %s\\n\\n\", event, data)\n w.(http.Flusher).Flush()\n}\n```\n\n**After:**\n\n```go\nvar bufPool = sync.Pool{\n New: func() interface{} { return new(bytes.Buffer) },\n}\n\nfunc writeEvent(w http.ResponseWriter, event, data string) {\n buf := bufPool.Get().(*bytes.Buffer)\n buf.Reset()\n defer bufPool.Put(buf)\n\n buf.WriteString(\"event: \")\n buf.WriteString(event)\n buf.WriteString(\"\\ndata: \")\n buf.WriteString(data)\n buf.WriteString(\"\\n\\n\")\n\n w.Write(buf.Bytes())\n w.(http.Flusher).Flush()\n}\n```\n\n**Benchmark:**\n\n```go\nfunc BenchmarkWriteEvent(b *testing.B) {\n w := httptest.NewRecorder()\n b.ResetTimer()\n for i := 0; i < b.N; i++ {\n writeEvent(w, \"test\", \"data\")\n }\n}\n```\n\n## Contributing Guidelines\n\n### Pull Request Process\n\n1. **Fork and clone** the repository\n2. **Create feature branch** from `main`\n3. **Implement changes** following coding standards\n4. **Add tests** for new functionality\n5. **Run all tests** and ensure they pass\n6. **Update documentation** as needed\n7. **Submit PR** with clear description\n\n### Code Review Standards\n\nReviewers check for:\n\n- [ ] Correctness and functionality\n- [ ] Test coverage\n- [ ] Code style and formatting\n- [ ] Documentation completeness\n- [ ] Performance implications\n- [ ] Security considerations\n- [ ] Error handling\n- [ ] Backwards compatibility\n\n### Release Checklist\n\nBefore releasing:\n\n- [ ] All tests pass (unit, integration, e2e)\n- [ ] Documentation updated (README, DEVELOPMENT, API docs)\n- [ ] CHANGELOG updated with changes\n- [ ] Version bumped appropriately (semver)\n- [ ] Dependencies reviewed and updated\n- [ ] Security scan passed\n- [ ] Performance benchmarks run\n- [ ] Docker image built and tested\n\n## Additional Resources\n\n### Useful Commands\n\n```bash\n# Format all Go files\nmake fmt\n\n# Run linter\nmake golint\n\n# Run all tests\nmake test\n\n# Build binary\nmake build\n```\n\n### External Documentation\n\n- [Beego Documentation](https://beego.wiki/)\n- [Jupyter Kernel Protocol](https://jupyter-client.readthedocs.io/en/stable/messaging.html)\n- [Go Best Practices](https://golang.org/doc/effective_go)\n- [Server-Sent Events Spec](https://html.spec.whatwg.org/multipage/server-sent-events.html)\n\n### Getting Help\n\n- **Issues**: Report bugs or request features on GitHub Issues\n- **Discussions**: Ask questions in GitHub Discussions\n- **Chat**: Join the OpenSandbox community chat\n- **Documentation**: Check the wiki for detailed guides\n\n---\n\n**Happy hacking!** Feel free to augment this guide with tips you discover along the way. For questions or suggestions,\nopen an issue or discussion on GitHub.\n" }, { "path": "components/execd/Dockerfile", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nFROM golang:1.24.0 AS builder\n\nWORKDIR /build\n\nARG VERSION=dev\nARG GIT_COMMIT=unknown\nARG BUILD_TIME=unknown\n\n# Prepare local modules to satisfy replace directives.\nCOPY components/internal/go.mod components/internal/go.sum ./components/internal/\nCOPY components/execd/go.mod components/execd/go.sum ./components/execd/\n\n# Download deps with only mod files for better caching.\nRUN cd components/internal && go mod download\nRUN cd components/execd && go mod download\n\n# Copy sources.\nCOPY components/internal ./components/internal\nCOPY components/execd ./components/execd\n\nWORKDIR /build/components/execd\n\nRUN CGO_ENABLED=0 go build \\\n -ldflags \"-X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \\\n -X 'github.com/alibaba/opensandbox/internal/version.BuildTime=${BUILD_TIME}' \\\n -X 'github.com/alibaba/opensandbox/internal/version.GitCommit=${GIT_COMMIT}'\" \\\n -o /build/execd ./main.go\n\nFROM alpine:latest\n\nCOPY --from=builder /build/execd .\nCOPY components/execd/bootstrap.sh ./bootstrap.sh\n\nENTRYPOINT [\"./execd\"]\n" }, { "path": "components/execd/Makefile", "content": ".PHONY: fmt\nfmt: ## Run go fmt against code.\n\tgo fmt ./...\n\n.PHONY: vet\nvet: ## Run go vet against code.\n\tgo mod tidy && go mod vendor\n\tgo vet ./...\n\n.PHONY: test\ntest: vet ## Run tests\n\tgo test -v -coverpkg=./... ./pkg/...\n\n##@ Linter\n\n.PHONY: install-golint\ninstall-golint:\n\t@if ! command -v golangci-lint &> /dev/null; then \\\n \t\techo \"installing golangci-lint...\"; \\\n \t\tgo install github.com/golangci/golangci-lint/cmd/golangci-lint@latest; \\\n \telse \\\n \t echo \"golangci-lint already installed\"; \\\n\tfi\n\n.PHONY: golint\ngolint: fmt install-golint\n\tgolangci-lint run -v --fix ./...\n\nVERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo \"dev\")\nGIT_COMMIT ?= $(shell git rev-parse HEAD 2>/dev/null || echo \"unknown\")\nBUILD_TIME ?= $(shell date -u +\"%Y-%m-%dT%H:%M:%SZ\")\nLDFLAGS := -X 'github.com/alibaba/opensandbox/internal/version.Version=$(VERSION)' \\\n\t-X 'github.com/alibaba/opensandbox/internal/version.BuildTime=$(BUILD_TIME)' \\\n\t-X 'github.com/alibaba/opensandbox/internal/version.GitCommit=$(GIT_COMMIT)'\n\n.PHONY: build\nbuild: vet ## Build the binary.\n\t@mkdir -p bin\n\tgo build -ldflags \"$(LDFLAGS)\" -o bin/execd main.go\n\n.PHONY: multi-build\nmulti-build: vet ## Cross-compile for linux/windows/darwin amd64/arm64.\n\t@mkdir -p bin\n\t@for os in linux windows darwin; do \\\n\t\tfor arch in amd64 arm64; do \\\n\t\t\tout=bin/execd-$${os}-$${arch}; \\\n\t\t\t[ \"$${os}\" = \"windows\" ] && out=\"$${out}.exe\"; \\\n\t\t\techo \">> building $${os}/$${arch} -> $${out}\"; \\\n\t\t\tGOOS=$${os} GOARCH=$${arch} CGO_ENABLED=0 go build -ldflags \"$(LDFLAGS)\" -o \"$${out}\" main.go || exit $$?; \\\n\t\tdone; \\\n\tdone\n" }, { "path": "components/execd/README.md", "content": "# execd - OpenSandbox Execution Daemon\n\nEnglish | [ไธญๆ–‡](README_zh.md)\n\n`execd` is the execution daemon for OpenSandbox. Built on Beego, it exposes a comprehensive HTTP API that turns external requests into runtime actions: managing Jupyter sessions, streaming code output via Server-Sent Events (SSE), executing shell commands, operating on the sandbox filesystem, and collecting host-side metrics.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Core Features](#core-features)\n- [Architecture](#architecture)\n- [Getting Started](#getting-started)\n- [Configuration](#configuration)\n- [API Reference](#api-reference)\n- [Supported Languages](#supported-languages)\n- [Development](#development)\n- [Testing](#testing)\n- [Observability](#observability)\n- [Performance Benchmarks](#performance-benchmarks)\n- [Contributing](#contributing)\n- [License](#license)\n- [Support](#support)\n\n## Overview\n\n`execd` provides a unified interface for:\n\n- **Code execution**: Python, Java, JavaScript, TypeScript, Go, and Bash\n- **Session management**: Long-lived Jupyter kernel sessions with state\n- **Command execution**: Synchronous and background shell commands\n- **File operations**: Full filesystem CRUD with chunked upload/download\n- **Monitoring**: Real-time host metrics (CPU, memory, uptime)\n\n## Core Features\n\n### Unified runtime management\n\n- Translate REST calls into runtime requests handled by `pkg/runtime`\n- Multiple execution backends: Jupyter, shell, etc.\n- Automatic language detection and routing\n- Pluggable Jupyter server configuration\n\n### Jupyter integration\n\n- Maintain kernel sessions via `pkg/jupyter`\n- WebSocket-based real-time communication\n- Stream execution events through SSE\n\n### Command executor\n\n- Foreground and background shell commands\n- Proper signal forwarding with process groups\n- Real-time stdout/stderr streaming\n- Context-aware interruption\n\n### Filesystem\n\n- CRUD helpers around the sandbox filesystem\n- Glob-based file search\n- Chunked upload/download with resume support\n- Permission management\n\n### Observability\n\n- Lightweight metrics endpoint (CPU, memory, uptime)\n- Structured streaming logs\n- SSE-based real-time monitoring\n\n## Architecture\n\n### Directory structure\n\n| Path | Purpose |\n|------------------------|------------------------------------------------------|\n| `main.go` | Entry point; initializes Beego, CLI flags, routers |\n| `pkg/flag/` | CLI and environment configuration |\n| `pkg/web/` | HTTP layer (controllers, models, router, SSE helpers) |\n| `pkg/web/controller/` | Handlers for files, code, commands, metrics |\n| `pkg/web/model/` | Request/response models and SSE event types |\n| `pkg/runtime/` | Dispatcher to Jupyter and shell executors |\n| `pkg/jupyter/` | Minimal Jupyter client (kernels/sessions/WebSocket) |\n| `pkg/jupyter/execute/` | Execution result types and stream parsers |\n| `pkg/jupyter/session/` | Session management and lifecycle |\n| `pkg/util/` | Utilities (safe goroutine helpers, glob helpers) |\n| `tests/` | Test scripts and tools |\n\n## Getting Started\n\n### Prerequisites\n\n- **Go 1.24+** (as defined in `go.mod`)\n- **Jupyter Server** (required for code execution)\n- **Docker** (optional, for containerized builds)\n- **Make** (optional, for convenience targets)\n\n### Quick Start\n\n#### 1. Clone and build\n\n```bash\ngit clone git@github.com:alibaba/OpenSandbox.git\ncd OpenSandbox/components/execd\ngo mod download\nmake build\n```\n\n#### 2. Start Jupyter Server\n\n```bash\n# Option 1: use the provided script\n./tests/jupyter.sh\n\n# Option 2: start manually\njupyter notebook --port=54321 --no-browser --ip=0.0.0.0 \\\n --NotebookApp.token='your-jupyter-token'\n```\n\n#### 3. Run execd\n\n```bash\n./bin/execd \\\n --jupyter-host=http://127.0.0.1:54321 \\\n --jupyter-token=your-jupyter-token \\\n --port=44772\n```\n\n#### 4. Verify\n\n```bash\ncurl -v http://localhost:44772/ping\n# Expect HTTP 200\n```\n\n### Image build\n\n```bash\ndocker build -t opensandbox/execd:dev .\n\n# Run container\ndocker run -d \\\n -p 44772:44772 \\\n -e JUPYTER_HOST=http://jupyter-server \\\n -e JUPYTER_TOKEN=your-token \\\n --name execd \\\n opensandbox/execd:dev\n```\n\n## Configuration\n\n### Command-line flags\n\n| Flag | Type | Default | Description |\n|-------------------------------|----------|---------|-----------------------------------------------|\n| `--jupyter-host` | string | `\"\"` | Jupyter server URL (reachable by execd) |\n| `--jupyter-token` | string | `\"\"` | Jupyter HTTP/WebSocket token |\n| `--port` | int | `44772` | HTTP listen port |\n| `--log-level` | int | `6` | Beego log level (0=Emergency, 7=Debug) |\n| `--access-token` | string | `\"\"` | Shared API secret (optional) |\n| `--graceful-shutdown-timeout` | duration | `3s` | Wait time before cutting off SSE on shutdown |\n\n### Environment variables\n\nAll flags can be set via environment variables:\n\n```bash\nexport JUPYTER_HOST=http://127.0.0.1:8888\nexport JUPYTER_TOKEN=your-token\n```\n\nEnvironment variables override defaults but are superseded by explicit CLI flags.\n\n## API Reference\n\n[API Spec](../../specs/execd-api.yaml).\n\n## Supported Languages\n\n### Jupyter-based\n\n| Language | Kernel | Highlights |\n|------------|-------------|-----------------------------|\n| Python | IPython | Full Jupyter protocol |\n| Java | IJava | JShell-based execution |\n| JavaScript | IJavaScript | Node.js runtime |\n| TypeScript | ITypeScript | TS compilation + Node exec |\n| Go | gophernotes | Go interpreter |\n| Bash | Bash kernel | Shell scripts |\n\n### Native executors\n\n| Mode/Language | Backend | Highlights |\n|----------------------|---------|------------------------------|\n| `command` | OS exec | Synchronous shell commands |\n| `background-command` | OS exec | Detached background process |\n\n## Development\n\nSee [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed guidelines.\n\n## Testing\n\n### Unit tests\n\n```bash\nmake test\n```\n\n### Integration tests\n\nIntegration tests requiring a real Jupyter Server are skipped by default:\n\n```bash\nexport JUPYTER_URL=http://localhost:8888\nexport JUPYTER_TOKEN=your-token\ngo test -v ./pkg/jupyter/...\n```\n\n### Manual testing workflow\n\n1. Start Jupyter: `./tests/jupyter.sh`\n2. Start execd: `./bin/execd --jupyter-host=http://localhost:54321 --jupyter-token=opensandboxexecdlocaltest`\n3. Execute code:\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \\\n -d '{\"language\":\"python\",\"code\":\"print(\\\"test\\\")\"}' \\\n http://localhost:44772/code\n```\n\n## Configuration\n\n### API graceful shutdown window\n\n- Env: `EXECD_API_GRACE_SHUTDOWN` (e.g. `500ms`, `2s`, `1m`)\n- Flag: `--graceful-shutdown-timeout`\n- Default: `1s`\n\nThis controls how long execd keeps SSE responses (code/command runs) alive after sending the final chunk, so clients can drain tail output before the connection closes. Set to `0s` to disable the grace period.\n\n## Observability\n\n### Logging\n\nBeego leveled logger:\n\n```go\nlogs.Info(\"message\") // info\nlogs.Warning(\"message\") // warning\nlogs.Error(\"message\") // error\nlogs.Debug(\"message\") // debug\n```\n\n- Env: `EXECD_LOG_FILE` writes execd logs to the given file path; when unset, logs are sent to stdout.\n\nLog levels (0-7):\n\n- 0: Emergency\n- 1: Alert\n- 2: Critical\n- 3: Error\n- 4: Warning\n- 5: Notice\n- 6: Info (default)\n- 7: Debug\n\n### Metrics\n\n`/metrics` exposes:\n\n- CPU usage percent\n- Memory total/used (GB)\n- Memory usage percent\n- Process uptime\n- Current timestamp\n\nFor real-time monitoring, use `/metrics/watch` (SSE, 1s cadence).\n\n## Performance Benchmarks\n\n### Typical latency (localhost)\n\n| Operation | Latency |\n|---------------------|----------|\n| `/ping` | < 1ms |\n| `/files/info` | < 5ms |\n| Code execution (Py) | 50-200ms |\n| File upload (1MB) | 10-50ms |\n| Metrics snapshot | < 10ms |\n\n### Resource usage (idle)\n\n- Memory: ~50MB\n- CPU: < 1%\n- Goroutines: ~15\n\n### Scalability\n\n- 100+ concurrent SSE connections\n- File operations scale linearly with file size\n- Jupyter sessions are stateful and need dedicated resources\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Follow coding conventions (see DEVELOPMENT.md)\n4. Add tests for new functionality\n5. Run `make fmt` and `make test`\n6. Submit a pull request\n\n## License\n\n`execd` is part of the OpenSandbox project. See [LICENSE](../../LICENSE) in the repository root.\n\n## Support\n\n- Issues: [GitHub Issues](https://github.com/alibaba/OpenSandbox/issues)\n- Documentation: [OpenSandbox Docs](https://github.com/alibaba/OpenSandbox/wiki)\n- Community: [Discussions](https://github.com/alibaba/OpenSandbox/discussions)\n" }, { "path": "components/execd/README_zh.md", "content": "# execd - OpenSandbox ๆ‰ง่กŒๅฎˆๆŠค่ฟ›็จ‹\n\nไธญๆ–‡ | [English](README.md)\n\n`execd` ๆ˜ฏ OpenSandbox ็š„ๆ‰ง่กŒๅฎˆๆŠค่ฟ›็จ‹๏ผŒๅŸบไบŽ Beego ๆก†ๆžถๆไพ›ๅ…จ้ข็š„ HTTP APIใ€‚ๅฎƒๅฐ†ๅค–้ƒจ่ฏทๆฑ‚่ฝฌๅŒ–ไธบๅฎž้™…็š„่ฟ่กŒๆ—ถๅŠจไฝœ๏ผš็ฎก็† Jupyter\nไผš่ฏใ€ไปฅ SSE๏ผˆServer-Sent Events๏ผ‰ๆตๅผ่ฟ”ๅ›žไปฃ็ ่พ“ๅ‡บใ€ๆ‰ง่กŒ shell ๅ‘ฝไปคใ€ๆ“ไฝœๆฒ™็ฎฑๆ–‡ไปถ็ณป็ปŸ๏ผŒๅนถ้‡‡้›†ไธปๆœบไพงๆŒ‡ๆ ‡ใ€‚\n\n## ็›ฎๅฝ•\n\n- [ๆฆ‚่ฟฐ](#ๆฆ‚่ฟฐ)\n- [ๆ ธๅฟƒ็‰นๆ€ง](#ๆ ธๅฟƒ็‰นๆ€ง)\n- [ๆžถๆž„่ฎพ่ฎก](#ๆžถๆž„่ฎพ่ฎก)\n- [ๅฟซ้€Ÿๅผ€ๅง‹](#ๅฟซ้€Ÿๅผ€ๅง‹)\n- [้…็ฝฎ่ฏดๆ˜Ž](#้…็ฝฎ่ฏดๆ˜Ž)\n- [API ๅ‚่€ƒ](#api-ๅ‚่€ƒ)\n- [ๆ”ฏๆŒ็š„่ฏญ่จ€](#ๆ”ฏๆŒ็š„่ฏญ่จ€)\n- [ๅผ€ๅ‘ๆŒ‡ๅ—](#ๅผ€ๅ‘ๆŒ‡ๅ—)\n- [ๆต‹่ฏ•](#ๆต‹่ฏ•)\n- [ๅฏ่ง‚ๆต‹ๆ€ง](#ๅฏ่ง‚ๆต‹ๆ€ง)\n- [่ฎธๅฏ่ฏ](#่ฎธๅฏ่ฏ)\n\n## ๆฆ‚่ฟฐ\n\n`execd` ไฝœไธบ OpenSandbox ็š„่ฟ่กŒๆ—ถๅฎˆๆŠค่ฟ›็จ‹๏ผŒๆไพ›็ปŸไธ€็š„ๆŽฅๅฃ็”จไบŽ๏ผš\n\n- **ไปฃ็ ๆ‰ง่กŒ**๏ผšPythonใ€Javaใ€JavaScriptใ€TypeScriptใ€Go ๅ’Œ Bash\n- **ไผš่ฏ็ฎก็†**๏ผšๅธฆ็Šถๆ€ไฟๆŒ็š„้•ฟ่ฟžๆŽฅ Jupyter kernel ไผš่ฏ\n- **ๅ‘ฝไปคๆ‰ง่กŒ**๏ผšๅŒๆญฅๆ‰ง่กŒๅ’Œๅผ‚ๆญฅๆ‰ง่กŒ shell ๅ‘ฝไปค\n- **ๆ–‡ไปถๆ“ไฝœ**๏ผšๅฎŒๆ•ด็š„ๆ–‡ไปถ็ณป็ปŸ CRUD๏ผŒๆ”ฏๆŒๅˆ†ๅ—ไธŠไผ /ไธ‹่ฝฝ\n- **็›‘ๆŽง**๏ผšๅฎžๆ—ถ็ณป็ปŸๆŒ‡ๆ ‡๏ผˆCPUใ€ๅ†…ๅญ˜ใ€่ฟ่กŒๆ—ถ้—ด๏ผ‰\n\n## ๆ ธๅฟƒ็‰นๆ€ง\n\n### ็ปŸไธ€่ฟ่กŒๆ—ถ็ฎก็†\n\n- ๅฐ† REST ่ฐƒ็”จ่ฝฌๅŒ–ไธบ็”ฑ `pkg/runtime` ๆŽงๅˆถๅ™จๅค„็†็š„่ฟ่กŒๆ—ถ่ฏทๆฑ‚\n- ๆ”ฏๆŒๅคš็งๆ‰ง่กŒๅŽ็ซฏ๏ผšJupyterใ€Shellใ€็ญ‰็ญ‰\n- ่‡ชๅŠจ่ฏญ่จ€ๆฃ€ๆต‹ๅ’Œ่ทฏ็”ฑ\n- ๅฏๆ’ๆ‹” Jupyter server ้…็ฝฎ\n\n### Jupyter ้›†ๆˆ\n\n- ้€š่ฟ‡ `pkg/jupyter` ็ปดๆŠค kernel ไผš่ฏ\n- ๅŸบไบŽ WebSocket ็š„ๅฎžๆ—ถ้€šไฟก\n- ้€š่ฟ‡ Server-Sent Events (SSE) ๆตๅผๆŽจ้€ๆ‰ง่กŒไบ‹ไปถ\n\n### ๅ‘ฝไปคๆ‰ง่กŒๅ™จ\n\n- ๅ‰ๅฐใ€ๅŽๅฐ shell ๅ‘ฝไปค\n- ้€š่ฟ‡่ฟ›็จ‹็ป„็ฎก็†ๆญฃ็กฎ่ฝฌๅ‘ไฟกๅท\n- ๅฎžๆ—ถ stdout/stderr ๆตๅผ่พ“ๅ‡บ\n- ๆ”ฏๆŒไธŠไธ‹ๆ–‡ๆ„Ÿ็Ÿฅ็š„ไธญๆ–ญ\n\n### ๆ–‡ไปถ็ณป็ปŸ\n\n- ๅ›ด็ป•ๆฒ™็ฎฑๆ–‡ไปถ็ณป็ปŸ็š„ CRUD ่พ…ๅŠฉๅทฅๅ…ท\n- Glob ๆจกๅผๅŒน้…ๆ–‡ไปถๆœ็ดข\n- ๆ”ฏๆŒๆ–ญ็‚น็ปญไผ ็š„ๅˆ†ๅ—ไธŠไผ /ไธ‹่ฝฝ\n- ๆƒ้™็ฎก็†\n\n### ๅฏ่ง‚ๆต‹ๆ€ง\n\n- ่ฝป้‡็บงๆŒ‡ๆ ‡็ซฏ็‚น๏ผˆCPUใ€ๅ†…ๅญ˜ใ€่ฟ่กŒๆ—ถ้—ด๏ผ‰\n- ็ป“ๆž„ๅŒ–ๆตๅผๆ—ฅๅฟ—\n- ๅŸบไบŽ SSE ็š„ๅฎžๆ—ถ็›‘ๆŽง\n\n## ๆžถๆž„่ฎพ่ฎก\n\n### ็›ฎๅฝ•็ป“ๆž„\n\n| ่ทฏๅพ„ | ่ฏดๆ˜Ž |\n|------------------------|--------------------------------------------|\n| `main.go` | ็จ‹ๅบๅ…ฅๅฃ๏ผŒๅˆๅง‹ๅŒ– Beegoใ€CLI ๆ ‡ๅฟ—ๅ’Œ่ทฏ็”ฑ |\n| `pkg/flag/` | ๅ‘ฝไปค่กŒไธŽ็Žฏๅขƒๅ˜้‡้…็ฝฎ |\n| `pkg/web/` | HTTP ๅฑ‚๏ผˆๆŽงๅˆถๅ™จใ€ๆจกๅž‹ใ€่ทฏ็”ฑใ€SSE ่พ…ๅŠฉ๏ผ‰ |\n| `pkg/web/controller/` | ๆ–‡ไปถใ€ไปฃ็ ใ€ๅ‘ฝไปคใ€ๆŒ‡ๆ ‡็š„่ฏทๆฑ‚ๅค„็†ๅ™จ |\n| `pkg/web/model/` | ่ฏทๆฑ‚/ๅ“ๅบ”ๆจกๅž‹ไธŽ SSE ไบ‹ไปถ็ฑปๅž‹ |\n| `pkg/runtime/` | ่ฟ่กŒๆ—ถๆŽงๅˆถๅ™จ๏ผŒ่ฐƒๅบฆๅˆฐ Jupyterใ€Shellๆ‰ง่กŒๅ™จ |\n| `pkg/jupyter/` | ็ฒพ็ฎ€ Jupyter ๅฎขๆˆท็ซฏ๏ผˆkernels/sessions/WebSocket๏ผ‰ |\n| `pkg/jupyter/execute/` | ๆ‰ง่กŒ็ป“ๆžœ็ฑปๅž‹ไธŽๆต่งฃๆžๅ™จ |\n| `pkg/jupyter/session/` | ไผš่ฏ็ฎก็†ไธŽ็”Ÿๅ‘ฝๅ‘จๆœŸ |\n| `pkg/util/` | ้€š็”จๅทฅๅ…ท๏ผˆๅฎ‰ๅ…จ goroutineใ€glob ่พ…ๅŠฉ๏ผ‰ |\n| `tests/` | ๆต‹่ฏ•่„šๆœฌๅ’Œๅทฅๅ…ท |\n\n## ๅฟซ้€Ÿๅผ€ๅง‹\n\n### ็Žฏๅขƒ่ฆๆฑ‚\n\n- **Go 1.24+**๏ผˆๅœจ `go.mod` ไธญๅฎšไน‰๏ผ‰\n- **Jupyter Server**๏ผˆไปฃ็ ๆ‰ง่กŒไธŠไธ‹ๆ–‡ๆ‰€้œ€๏ผ‰\n- **Docker**๏ผˆๅฏ้€‰๏ผŒ็”จไบŽๅฎนๅ™จๅŒ–ๆž„ๅปบ๏ผ‰\n- **Make**๏ผˆๅฏ้€‰๏ผŒ็”จไบŽไพฟๆทๅ‘ฝไปค๏ผ‰\n\n### ๅฟซ้€ŸๅฏๅŠจ\n\n#### 1. ๅ…‹้š†ๅนถๆž„ๅปบ\n\n```bash\ngit clone git@github.com:alibaba/OpenSandbox.git\ncd OpenSandbox/components/execd\ngo mod download\nmake build\n```\n\n#### 2. ๅฏๅŠจ Jupyter Server\n\n```bash\n# ๆ–นๅผ 1๏ผšไฝฟ็”จๆไพ›็š„่„šๆœฌ\n./tests/jupyter.sh\n\n# ๆ–นๅผ 2๏ผšๆ‰‹ๅŠจๅฏๅŠจ\njupyter notebook --port=54321 --no-browser --ip=0.0.0.0 \\\n --NotebookApp.token='your-jupyter-token'\n```\n\n#### 3. ่ฟ่กŒ execd\n\n```bash\n./bin/execd \\\n --jupyter-host=http://127.0.0.1:54321 \\\n --jupyter-token=your-jupyter-token \\\n --port=44772\n```\n\n#### 4. ้ชŒ่ฏๅฎ‰่ฃ…\n\n```bash\ncurl -v http://localhost:44772/ping\n# ๆœŸๆœ›200็Šถๆ€็ \n```\n\n### ้•œๅƒๆž„ๅปบ\n\n```bash\ndocker build -t opensandbox/execd:dev .\n\n# ่ฟ่กŒๅฎนๅ™จ\ndocker run -d \\\n -p 44772:44772 \\\n -e JUPYTER_HOST=http://jupyter-server \\\n -e JUPYTER_TOKEN=your-token \\\n --name execd \\\n opensandbox/execd:dev\n```\n\n## ้…็ฝฎ่ฏดๆ˜Ž\n\n### ๅ‘ฝไปค่กŒๆ ‡ๅฟ—\n\n| ๆ ‡ๅฟ— | ็ฑปๅž‹ | ้ป˜่ฎคๅ€ผ | ่ฏดๆ˜Ž |\n|-------------------------------|----------|---------|-------------------------------------|\n| `--jupyter-host` | string | `\"\"` | ๅŽ็ซฏ Jupyter server ๅœฐๅ€๏ผŒ่ฆๆฑ‚execd่ฟ›็จ‹ๅฏ่ฎฟ้—ฎๅณๅฏ |\n| `--jupyter-token` | string | `\"\"` | Jupyter HTTP/WebSocket ไปค็‰Œ |\n| `--port` | int | `44772` | HTTP ็›‘ๅฌ็ซฏๅฃ |\n| `--log-level` | int | `6` | Beego ๆ—ฅๅฟ—็บงๅˆซ๏ผˆ0=็ดงๆ€ฅ๏ผŒ7=่ฐƒ่ฏ•๏ผ‰ |\n| `--access-token` | string | `\"\"` | API ๅ…ฑไบซๅฏ†้’ฅ๏ผˆๅฏ้€‰๏ผ‰ |\n| `--graceful-shutdown-timeout` | duration | `3s` | ๅ…ณ้—ญๅ‰็ญ‰ๅพ… SSE ็š„ๆ—ถ้—ด |\n\n### ็Žฏๅขƒๅ˜้‡\n\nๆ‰€ๆœ‰ๆ ‡ๅฟ—้ƒฝๅฏไปฅ้€š่ฟ‡็Žฏๅขƒๅ˜้‡่ฎพ็ฝฎ๏ผš\n\n```bash\nexport JUPYTER_HOST=http://127.0.0.1:8888\nexport JUPYTER_TOKEN=your-token\n```\n\n็Žฏๅขƒๅ˜้‡ไผ˜ๅ…ˆไบŽ้ป˜่ฎคๅ€ผ๏ผŒไฝ†ไผš่ขซๆ˜พๅผ็š„ CLI ๆ ‡ๅฟ—่ฆ†็›–ใ€‚\n\n## API ๅ‚่€ƒ\n\n[API Spec](../../specs/execd-api.yaml)ใ€‚\n\n## ๆ”ฏๆŒ็š„่ฏญ่จ€\n\n### ๅŸบไบŽ Jupyter ็š„่ฏญ่จ€\n\n| ่ฏญ่จ€ | Kernel | ็‰นๆ€ง |\n|------------|-------------|-----------------|\n| Python | IPython | ๅฎŒๆ•ด Jupyter ๅ่ฎฎๆ”ฏๆŒ |\n| Java | IJava | ๅŸบไบŽ JShell ็š„ๆ‰ง่กŒ |\n| JavaScript | IJavaScript | Node.js ่ฟ่กŒๆ—ถ |\n| TypeScript | ITypeScript | TS ็ผ–่ฏ‘ + Node ๆ‰ง่กŒ |\n| Go | gophernotes | Go ่งฃ้‡Šๅ™จ |\n| Bash | Bash kernel | Shell ่„šๆœฌๆ‰ง่กŒ |\n\n### ๅŽŸ็”Ÿๆ‰ง่กŒๅ™จ\n\n| ๆจกๅผ/่ฏญ่จ€ | ๅŽ็ซฏ | ็‰นๆ€ง |\n|----------------------|---------|-------------|\n| `command` | OS exec | ๅŒๆญฅ shell ๅ‘ฝไปค |\n| `background-command` | OS exec | ๅˆ†็ฆป็š„ๅŽๅฐ่ฟ›็จ‹ |\n\n## ๅผ€ๅ‘ๆŒ‡ๅ—\n\nๅผ€ๅ‘ๆŒ‡ๅ—่ฏทๅ‚่ง [DEVELOPMENT.md](./DEVELOPMENT.md)ใ€‚\n\n## ๆต‹่ฏ•\n\n### ๅ•ๅ…ƒๆต‹่ฏ•\n\n```bash\nmake test\n```\n\n### ้›†ๆˆๆต‹่ฏ•\n\n้œ€่ฆ็œŸๅฎž Jupyter Server ็š„้›†ๆˆๆต‹่ฏ•้ป˜่ฎค่ทณ่ฟ‡๏ผš\n\n```bash\nexport JUPYTER_URL=http://localhost:8888\nexport JUPYTER_TOKEN=your-token\ngo test -v ./pkg/jupyter/...\n```\n\n### ๆ‰‹ๅŠจๆต‹่ฏ•ๅทฅไฝœๆต\n\n1. ๅฏๅŠจ Jupyter๏ผš`./tests/jupyter.sh`\n2. ๅฏๅŠจ execd๏ผš`./bin/execd --jupyter-host=http://localhost:54321 --jupyter-token=opensandboxexecdlocaltest`\n\n3. ๆ‰ง่กŒไปฃ็ ๏ผš\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \\\n -d '{\"language\":\"python\",\"code\":\"print(\\\"test\\\")\"}' \\\n http://localhost:44772/code\n```\n\n## ้…็ฝฎ\n\n### SSE API ไผ˜้›…็ป“ๆŸๆ—ถ้—ด็ช—ๅฃ\n\n- ็Žฏๅขƒๅ˜้‡๏ผš`EXECD_API_GRACE_SHUTDOWN`๏ผˆๅฆ‚ `500ms`ใ€`2s`ใ€`1m`๏ผ‰\n- ๅ‘ฝไปค่กŒๅ‚ๆ•ฐ๏ผš`--graceful-shutdown-timeout`\n- ้ป˜่ฎคๅ€ผ๏ผš`1s`\n\nไฝœ็”จ๏ผšๆŽงๅˆถ SSE ๅ“ๅบ”๏ผˆไปฃ็ /ๅ‘ฝไปคๆ‰ง่กŒ๏ผ‰ๅœจๅ‘้€ๆœ€ๅŽไธ€ๅ—ๆ•ฐๆฎๅŽ๏ผŒไฟๆŒ่ฟžๆŽฅ็š„ๅฎฝ้™ๆ—ถ้—ด๏ผŒๆ–นไพฟๅฎขๆˆท็ซฏๅฎŒๅ…จ่ฏปๅˆฐๅฐพ้ƒจ่พ“ๅ‡บๅ†ๅ…ณ้—ญใ€‚ๅฆ‚ๆžœ่ฎพ็ฝฎไธบ `0s` ๅˆ™ๅ…ณ้—ญ่ฟ™ไธ€็ญ‰ๅพ…ใ€‚\n\n## ๅฏ่ง‚ๆต‹ๆ€ง\n\n### ๆ—ฅๅฟ—่ฎฐๅฝ•\n\nๅ…จ็จ‹ไฝฟ็”จ Beego ็š„ๅˆ†็บงๆ—ฅๅฟ—ๅ™จ๏ผš\n\n```go\nlogs.Info(\"message\") // ๅธธ่ง„ไฟกๆฏ\nlogs.Warning(\"message\") // ่ญฆๅ‘Šๆกไปถ\nlogs.Error(\"message\") // ้”™่ฏฏๆกไปถ\nlogs.Debug(\"message\") // ่ฐƒ่ฏ•็บงๅˆซๆถˆๆฏ\n```\n\n- ็Žฏๅขƒๅ˜้‡๏ผš`EXECD_LOG_FILE` ๆŒ‡ๅฎšๆ—ฅๅฟ—่พ“ๅ‡บๆ–‡ไปถ๏ผ›ๆœช่ฎพ็ฝฎๆ—ถๆ—ฅๅฟ—่พ“ๅ‡บๅˆฐๆ ‡ๅ‡†่พ“ๅ‡บ๏ผˆstdout๏ผ‰ใ€‚\n\nๆ—ฅๅฟ—็บงๅˆซ๏ผˆ0-7๏ผ‰๏ผš\n\n- 0๏ผš็ดงๆ€ฅ\n- 1๏ผš่ญฆๆŠฅ\n- 2๏ผšไธฅ้‡\n- 3๏ผš้”™่ฏฏ\n- 4๏ผš่ญฆๅ‘Š\n- 5๏ผšๆณจๆ„\n- 6๏ผšไฟกๆฏ๏ผˆ้ป˜่ฎค๏ผ‰\n- 7๏ผš่ฐƒ่ฏ•\n\n### ๆŒ‡ๆ ‡้‡‡้›†\n\n`/metrics` ็ซฏ็‚นๆไพ›๏ผš\n\n- CPU ไฝฟ็”จ็™พๅˆ†ๆฏ”\n- ๅ†…ๅญ˜ๆ€ป้‡/ๅทฒ็”จ๏ผˆGB๏ผ‰\n- ๅ†…ๅญ˜ไฝฟ็”จ็™พๅˆ†ๆฏ”\n- ่ฟ›็จ‹่ฟ่กŒๆ—ถ้—ด\n- ๅฝ“ๅ‰ๆ—ถ้—ดๆˆณ\n\nๅฏนไบŽๅฎžๆ—ถ็›‘ๆŽง๏ผŒไฝฟ็”จ `/metrics/watch`๏ผŒๆฏ็ง’้€š่ฟ‡ SSE ๆตๅผๆŽจ้€ๆ›ดๆ–ฐใ€‚\n\n## ๆ€ง่ƒฝๅŸบๅ‡†\n\n### ๅ…ธๅž‹ๅปถ่ฟŸ๏ผˆlocalhost๏ผ‰\n\n| ๆ“ไฝœ | ๅปถ่ฟŸ |\n|---------------|----------|\n| `/ping` | < 1ms |\n| `/files/info` | < 5ms |\n| ไปฃ็ ๆ‰ง่กŒ๏ผˆPython๏ผ‰ | 50-200ms |\n| ๆ–‡ไปถไธŠไผ ๏ผˆ1MB๏ผ‰ | 10-50ms |\n| ๆŒ‡ๆ ‡ๅฟซ็…ง | < 10ms |\n\n### ่ต„ๆบไฝฟ็”จ๏ผˆ็ฉบ้—ฒ๏ผ‰\n\n- ๅ†…ๅญ˜๏ผš~50MB\n- CPU๏ผš< 1%\n- Goroutines๏ผš~15\n\n### ๅฏๆ‰ฉๅฑ•ๆ€ง\n\n- ๆ”ฏๆŒ 100+ ๅนถๅ‘ SSE ่ฟžๆŽฅ\n- ๆ–‡ไปถๆ“ไฝœ้šๆ–‡ไปถๅคงๅฐ็บฟๆ€งๆ‰ฉๅฑ•\n- Jupyter ไผš่ฏๆ˜ฏๆœ‰็Šถๆ€็š„๏ผŒ้œ€่ฆไธ“็”จ่ต„ๆบ\n\n## ่ดก็Œฎ\n\n1. Fork ไป“ๅบ“\n2. ๅˆ›ๅปบ็‰นๆ€งๅˆ†ๆ”ฏ\n3. ้ตๅพช็ผ–็ ่ง„่Œƒ๏ผˆ่ง DEVELOPMENT.md๏ผ‰\n4. ไธบๆ–ฐๅŠŸ่ƒฝๆทปๅŠ ๆต‹่ฏ•\n5. ่ฟ่กŒ `make fmt` ๅ’Œ `make test`\n6. ๆไบค pull request\n\n## ่ฎธๅฏ่ฏ\n\n`execd` ๆ˜ฏ OpenSandbox ้กน็›ฎ็š„ไธ€้ƒจๅˆ†ใ€‚่ฏฆ่งไป“ๅบ“ๆ น็›ฎๅฝ•็š„ [LICENSE](../../LICENSE)ใ€‚\n\n## ๆ”ฏๆŒ\n\n- ้—ฎ้ข˜๏ผš[GitHub Issues](https://github.com/alibaba/OpenSandbox/issues)\n- ๆ–‡ๆกฃ๏ผš[OpenSandbox Docs](https://github.com/alibaba/OpenSandbox/wiki)\n- ็คพๅŒบ๏ผš[Discussions](https://github.com/alibaba/OpenSandbox/discussions)\n" }, { "path": "components/execd/bootstrap.sh", "content": "#!/bin/sh\n\n# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nset -e\n\nEXECD=\"${EXECD:=/opt/opensandbox/execd}\"\n\nif [ -z \"${EXECD_ENVS:-}\" ]; then\n\tEXECD_ENVS=\"/opt/opensandbox/.env\"\nfi\n# Best-effort ensure file exists.\nif ! mkdir -p \"$(dirname \"$EXECD_ENVS\")\" 2>/dev/null; then\n\techo \"warning: failed to create dir for EXECD_ENVS=$EXECD_ENVS\" >&2\nfi\nif ! touch \"$EXECD_ENVS\" 2>/dev/null; then\n\techo \"warning: failed to touch EXECD_ENVS=$EXECD_ENVS\" >&2\nfi\nexport EXECD_ENVS\n\necho \"starting OpenSandbox Execd daemon at $EXECD.\"\n$EXECD &\n\n# Allow chained shell commands (e.g., /test1.sh && /test2.sh)\n# Usage:\n# bootstrap.sh -c \"/test1.sh && /test2.sh\"\n# Or set BOOTSTRAP_CMD=\"/test1.sh && /test2.sh\"\nCMD=\"\"\nif [ \"${BOOTSTRAP_CMD:-}\" != \"\" ]; then\n\tCMD=\"$BOOTSTRAP_CMD\"\nelif [ $# -ge 1 ] && [ \"$1\" = \"-c\" ]; then\n\tshift\n\tCMD=\"$*\"\nfi\n\nSHELL_BIN=\"${BOOTSTRAP_SHELL:-}\"\nif [ -z \"$SHELL_BIN\" ]; then\n\tif command -v bash >/dev/null 2>&1; then\n\t\tSHELL_BIN=\"$(command -v bash)\"\n\telif command -v sh >/dev/null 2>&1; then\n\t\tSHELL_BIN=\"$(command -v sh)\"\n\telse\n\t\techo \"error: neither bash nor sh found in PATH\" >&2\n\t\texit 1\n\tfi\nfi\n\nset -x\nif [ \"$CMD\" != \"\" ]; then\n\texec \"$SHELL_BIN\" -c \"$CMD\"\nfi\n\nif [ $# -eq 0 ]; then\n\texec \"$SHELL_BIN\"\nfi\n\nexec \"$@\"\n" }, { "path": "components/execd/build.sh", "content": "#!/bin/bash\n# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nset -ex\n\nTAG=${TAG:-latest}\nVERSION=${VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo \"dev\")}\nGIT_COMMIT=${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo \"unknown\")}\nBUILD_TIME=${BUILD_TIME:-$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")}\n\nREPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || realpath \"$(dirname \"$0\")/../..\")\ncd \"${REPO_ROOT}\"\n\ndocker buildx rm execd-builder || true\n\ndocker buildx create --use --name execd-builder\n\ndocker buildx inspect --bootstrap\n\ndocker buildx ls\n\nLATEST_TAGS=()\nif [[ \"${TAG}\" == v* ]]; then\n LATEST_TAGS+=(-t opensandbox/execd:latest -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:latest)\nfi\n\ndocker buildx build \\\n -t opensandbox/execd:${TAG} \\\n -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:${TAG} \\\n \"${LATEST_TAGS[@]}\" \\\n -f components/execd/Dockerfile \\\n --build-arg VERSION=\"${VERSION}\" \\\n --build-arg GIT_COMMIT=\"${GIT_COMMIT}\" \\\n --build-arg BUILD_TIME=\"${BUILD_TIME}\" \\\n --platform linux/amd64,linux/arm64 \\\n --push \\\n .\n" }, { "path": "components/execd/go.mod", "content": "module github.com/alibaba/opensandbox/execd\n\ngo 1.24.0\n\nrequire (\n\tgithub.com/alibaba/opensandbox/internal v0.0.0\n\tgithub.com/bmatcuk/doublestar/v4 v4.9.1\n\tgithub.com/gin-gonic/gin v1.10.0\n\tgithub.com/go-playground/validator/v10 v10.28.0\n\tgithub.com/go-sql-driver/mysql v1.8.1\n\tgithub.com/google/uuid v1.6.0\n\tgithub.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674\n\tgithub.com/shirou/gopsutil v3.21.11+incompatible\n\tgithub.com/stretchr/testify v1.10.0\n\tgo.uber.org/automaxprocs v1.6.0\n\tk8s.io/apimachinery v0.34.2\n\tk8s.io/client-go v0.34.2\n)\n\nrequire (\n\tfilippo.io/edwards25519 v1.1.1 // indirect\n\tgithub.com/bytedance/sonic v1.11.6 // indirect\n\tgithub.com/bytedance/sonic/loader v0.1.1 // indirect\n\tgithub.com/cloudwego/base64x v0.1.4 // indirect\n\tgithub.com/cloudwego/iasm v0.2.0 // indirect\n\tgithub.com/davecgh/go-spew v1.1.1 // indirect\n\tgithub.com/fxamacker/cbor/v2 v2.9.0 // indirect\n\tgithub.com/gabriel-vasile/mimetype v1.4.10 // indirect\n\tgithub.com/gin-contrib/sse v0.1.0 // indirect\n\tgithub.com/go-logr/logr v1.4.2 // indirect\n\tgithub.com/go-ole/go-ole v1.2.6 // indirect\n\tgithub.com/go-playground/locales v0.14.1 // indirect\n\tgithub.com/go-playground/universal-translator v0.18.1 // indirect\n\tgithub.com/goccy/go-json v0.10.2 // indirect\n\tgithub.com/gogo/protobuf v1.3.2 // indirect\n\tgithub.com/json-iterator/go v1.1.12 // indirect\n\tgithub.com/klauspost/cpuid/v2 v2.2.7 // indirect\n\tgithub.com/kr/pretty v0.3.1 // indirect\n\tgithub.com/leodido/go-urn v1.4.0 // indirect\n\tgithub.com/mattn/go-isatty v0.0.20 // indirect\n\tgithub.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect\n\tgithub.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect\n\tgithub.com/pelletier/go-toml/v2 v2.2.2 // indirect\n\tgithub.com/pmezard/go-difflib v1.0.0 // indirect\n\tgithub.com/tklauser/go-sysconf v0.3.16 // indirect\n\tgithub.com/tklauser/numcpus v0.11.0 // indirect\n\tgithub.com/twitchyliquid64/golang-asm v0.15.1 // indirect\n\tgithub.com/ugorji/go/codec v1.2.12 // indirect\n\tgithub.com/x448/float16 v0.8.4 // indirect\n\tgithub.com/yusufpapurcu/wmi v1.2.4 // indirect\n\tgo.uber.org/multierr v1.10.0 // indirect\n\tgo.uber.org/zap v1.27.0 // indirect\n\tgo.yaml.in/yaml/v2 v2.4.2 // indirect\n\tgolang.org/x/arch v0.8.0 // indirect\n\tgolang.org/x/crypto v0.45.0 // indirect\n\tgolang.org/x/net v0.47.0 // indirect\n\tgolang.org/x/sys v0.38.0 // indirect\n\tgolang.org/x/text v0.31.0 // indirect\n\tgoogle.golang.org/protobuf v1.36.5 // indirect\n\tgopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect\n\tgopkg.in/inf.v0 v0.9.1 // indirect\n\tgopkg.in/yaml.v3 v3.0.1 // indirect\n\tk8s.io/klog/v2 v2.130.1 // indirect\n\tk8s.io/utils v0.0.0-20250604170112-4c0f3b243397 // indirect\n\tsigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8 // indirect\n\tsigs.k8s.io/randfill v1.0.0 // indirect\n\tsigs.k8s.io/structured-merge-diff/v6 v6.3.0 // indirect\n)\n\nreplace github.com/alibaba/opensandbox/internal => ../internal\n" }, { "path": "components/execd/go.sum", "content": "filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw=\nfilippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=\ngithub.com/bmatcuk/doublestar/v4 v4.9.1 h1:X8jg9rRZmJd4yRy7ZeNDRnM+T3ZfHv15JiBJ/avrEXE=\ngithub.com/bmatcuk/doublestar/v4 v4.9.1/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=\ngithub.com/bytedance/sonic v1.11.6 h1:oUp34TzMlL+OY1OUWxHqsdkgC/Zfc85zGqw9siXjrc0=\ngithub.com/bytedance/sonic v1.11.6/go.mod h1:LysEHSvpvDySVdC2f87zGWf6CIKJcAvqab1ZaiQtds4=\ngithub.com/bytedance/sonic/loader v0.1.1 h1:c+e5Pt1k/cy5wMveRDyk2X4B9hF4g7an8N3zCYjJFNM=\ngithub.com/bytedance/sonic/loader v0.1.1/go.mod h1:ncP89zfokxS5LZrJxl5z0UJcsk4M4yY2JpfqGeCtNLU=\ngithub.com/cloudwego/base64x v0.1.4 h1:jwCgWpFanWmN8xoIUHa2rtzmkd5J2plF/dnLS6Xd/0Y=\ngithub.com/cloudwego/base64x v0.1.4/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJgA0rcu/8w=\ngithub.com/cloudwego/iasm v0.2.0 h1:1KNIy1I1H9hNNFEEH3DVnI4UujN+1zjpuk6gwHLTssg=\ngithub.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=\ngithub.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=\ngithub.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=\ngithub.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=\ngithub.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=\ngithub.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=\ngithub.com/fxamacker/cbor/v2 v2.9.0/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=\ngithub.com/gabriel-vasile/mimetype v1.4.10 h1:zyueNbySn/z8mJZHLt6IPw0KoZsiQNszIpU+bX4+ZK0=\ngithub.com/gabriel-vasile/mimetype v1.4.10/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=\ngithub.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=\ngithub.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=\ngithub.com/gin-gonic/gin v1.10.0 h1:nTuyha1TYqgedzytsKYqna+DfLos46nTv2ygFy86HFU=\ngithub.com/gin-gonic/gin v1.10.0/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=\ngithub.com/go-logr/logr v1.4.2 h1:6pFjapn8bFcIbiKo3XT4j/BhANplGihG6tvd+8rYgrY=\ngithub.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=\ngithub.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=\ngithub.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=\ngithub.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=\ngithub.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=\ngithub.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=\ngithub.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=\ngithub.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=\ngithub.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=\ngithub.com/go-playground/validator/v10 v10.28.0 h1:Q7ibns33JjyW48gHkuFT91qX48KG0ktULL6FgHdG688=\ngithub.com/go-playground/validator/v10 v10.28.0/go.mod h1:GoI6I1SjPBh9p7ykNE/yj3fFYbyDOpwMn5KXd+m2hUU=\ngithub.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y=\ngithub.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=\ngithub.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=\ngithub.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=\ngithub.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=\ngithub.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=\ngithub.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=\ngithub.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=\ngithub.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=\ngithub.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=\ngithub.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=\ngithub.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5THxAzdVpqr6/geYxZytqFMBCOtn/ujyeo=\ngithub.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=\ngithub.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=\ngithub.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=\ngithub.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=\ngithub.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=\ngithub.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=\ngithub.com/klauspost/cpuid/v2 v2.2.7 h1:ZWSB3igEs+d0qvnxR/ZBzXVmxkgt8DdzP6m9pfuVLDM=\ngithub.com/klauspost/cpuid/v2 v2.2.7/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws=\ngithub.com/knz/go-libedit v1.10.1/go.mod h1:MZTVkCWyz0oBc7JOWP3wNAzd002ZbM/5hgShxwh4x8M=\ngithub.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=\ngithub.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=\ngithub.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=\ngithub.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=\ngithub.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=\ngithub.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=\ngithub.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=\ngithub.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=\ngithub.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=\ngithub.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=\ngithub.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=\ngithub.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=\ngithub.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=\ngithub.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=\ngithub.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=\ngithub.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee h1:W5t00kpgFdJifH4BDsTlE89Zl93FEloxaWZfGcifgq8=\ngithub.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=\ngithub.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=\ngithub.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=\ngithub.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=\ngithub.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=\ngithub.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=\ngithub.com/prashantv/gostub v1.1.0 h1:BTyx3RfQjRHnUWaGF9oQos79AlQ5k8WNktv7VGvVH4g=\ngithub.com/prashantv/gostub v1.1.0/go.mod h1:A5zLQHz7ieHGG7is6LLXLz7I8+3LZzsrV0P1IAHhP5U=\ngithub.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=\ngithub.com/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=\ngithub.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=\ngithub.com/shirou/gopsutil v3.21.11+incompatible h1:+1+c1VGhc88SSonWP6foOcLhvnKlUeu/erjjvaPEYiI=\ngithub.com/shirou/gopsutil v3.21.11+incompatible/go.mod h1:5b4v6he4MtMOwMlS0TUMTu2PcXUg8+E1lC7eC3UO/RA=\ngithub.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=\ngithub.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=\ngithub.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=\ngithub.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=\ngithub.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=\ngithub.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=\ngithub.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=\ngithub.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=\ngithub.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=\ngithub.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=\ngithub.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=\ngithub.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=\ngithub.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=\ngithub.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=\ngithub.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=\ngithub.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA=\ngithub.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=\ngithub.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=\ngithub.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ=\ngithub.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=\ngithub.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=\ngithub.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=\ngithub.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=\ngithub.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=\ngithub.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=\ngithub.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=\ngithub.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=\ngithub.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=\ngithub.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=\ngo.uber.org/automaxprocs v1.6.0 h1:O3y2/QNTOdbF+e/dpXNNW7Rx2hZ4sTIPyybbxyNqTUs=\ngo.uber.org/automaxprocs v1.6.0/go.mod h1:ifeIMSnPZuznNm6jmdzmU3/bfk01Fe2fotchwEFJ8r8=\ngo.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=\ngo.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=\ngo.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=\ngo.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=\ngo.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=\ngo.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=\ngo.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=\ngo.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=\ngolang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=\ngolang.org/x/arch v0.8.0 h1:3wRIsP3pM4yUptoR96otTUOXI367OS0+c9eeRi9doIc=\ngolang.org/x/arch v0.8.0/go.mod h1:FEVrYAQjsQXMVJ1nsMoVVXPZg6p2JE2mx8psSWTDQys=\ngolang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=\ngolang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=\ngolang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=\ngolang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=\ngolang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=\ngolang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=\ngolang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=\ngolang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=\ngolang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=\ngolang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=\ngolang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=\ngolang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=\ngolang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=\ngolang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=\ngolang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=\ngolang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=\ngolang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=\ngolang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=\ngolang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=\ngolang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=\ngolang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=\ngolang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=\ngolang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=\ngolang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=\ngolang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=\ngolang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=\ngolang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=\ngolang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=\ngolang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=\ngolang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=\ngolang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=\ngolang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=\ngolang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=\ngolang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=\ngolang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=\ngolang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=\ngoogle.golang.org/protobuf v1.36.5 h1:tPhr+woSbjfYvY6/GPufUoYizxw1cF/yFoxJ2fmpwlM=\ngoogle.golang.org/protobuf v1.36.5/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=\ngopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=\ngopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=\ngopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=\ngopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=\ngopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=\ngopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=\ngopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=\ngopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=\nk8s.io/apimachinery v0.34.2 h1:zQ12Uk3eMHPxrsbUJgNF8bTauTVR2WgqJsTmwTE/NW4=\nk8s.io/apimachinery v0.34.2/go.mod h1:/GwIlEcWuTX9zKIg2mbw0LRFIsXwrfoVxn+ef0X13lw=\nk8s.io/client-go v0.34.2 h1:Co6XiknN+uUZqiddlfAjT68184/37PS4QAzYvQvDR8M=\nk8s.io/client-go v0.34.2/go.mod h1:2VYDl1XXJsdcAxw7BenFslRQX28Dxz91U9MWKjX97fE=\nk8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=\nk8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=\nk8s.io/utils v0.0.0-20250604170112-4c0f3b243397 h1:hwvWFiBzdWw1FhfY1FooPn3kzWuJ8tmbZBHi4zVsl1Y=\nk8s.io/utils v0.0.0-20250604170112-4c0f3b243397/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=\nnullprogram.com/x/optparse v1.0.0/go.mod h1:KdyPE+Igbe0jQUrVfMqDMeJQIJZEuyV7pjYmp6pbG50=\nrsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=\nsigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8 h1:gBQPwqORJ8d8/YNZWEjoZs7npUVDpVXUUOFfW6CgAqE=\nsigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8/go.mod h1:mdzfpAEoE6DHQEN0uh9ZbOCuHbLK5wOm7dK4ctXE9Tg=\nsigs.k8s.io/randfill v1.0.0 h1:JfjMILfT8A6RbawdsK2JXGBR5AQVfd+9TbzrlneTyrU=\nsigs.k8s.io/randfill v1.0.0/go.mod h1:XeLlZ/jmk4i1HRopwe7/aU3H5n1zNUcX6TM94b3QxOY=\nsigs.k8s.io/structured-merge-diff/v6 v6.3.0 h1:jTijUJbW353oVOd9oTlifJqOGEkUw2jB/fXCbTiQEco=\nsigs.k8s.io/structured-merge-diff/v6 v6.3.0/go.mod h1:M3W8sfWvn2HhQDIbGWj3S099YozAsymCo/wrT5ohRUE=\nsigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=\nsigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=\n" }, { "path": "components/execd/main.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/alibaba/opensandbox/internal/version\"\n\n\t_ \"go.uber.org/automaxprocs/maxprocs\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/flag\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n\t_ \"github.com/alibaba/opensandbox/execd/pkg/util/safego\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/controller\"\n)\n\n// main initializes and starts the execd server.\nfunc main() {\n\tversion.EchoVersion(\"OpenSandbox Execd\")\n\n\tflag.InitFlags()\n\n\tlog.Init(flag.ServerLogLevel)\n\n\tcontroller.InitCodeRunner()\n\tengine := web.NewRouter(flag.ServerAccessToken)\n\taddr := fmt.Sprintf(\":%d\", flag.ServerPort)\n\tlog.Info(\"execd listening on %s\", addr)\n\tif err := engine.Run(addr); err != nil {\n\t\tlog.Error(\"failed to start execd server: %v\", err)\n\t\tos.Exit(1)\n\t}\n}\n" }, { "path": "components/execd/pkg/flag/flags.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage flag\n\nimport \"time\"\n\nvar (\n\t// JupyterServerHost points to the target Jupyter instance.\n\tJupyterServerHost string\n\n\t// JupyterServerToken authenticates requests to the Jupyter server.\n\tJupyterServerToken string\n\n\t// ServerPort controls the HTTP listener port.\n\tServerPort int\n\n\t// ServerLogLevel controls the server log verbosity.\n\tServerLogLevel int\n\n\t// ServerAccessToken guards API entrypoints when set.\n\tServerAccessToken string\n\n\t// ApiGracefulShutdownTimeout waits before tearing down SSE streams.\n\tApiGracefulShutdownTimeout time.Duration\n)\n" }, { "path": "components/execd/pkg/flag/parser.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage flag\n\nimport (\n\t\"flag\"\n\tstdlog \"log\"\n\t\"os\"\n\t\"strings\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\nconst (\n\tjupyterHostEnv = \"JUPYTER_HOST\"\n\tjupyterTokenEnv = \"JUPYTER_TOKEN\"\n\tgracefulShutdownTimeoutEnv = \"EXECD_API_GRACE_SHUTDOWN\"\n)\n\n// InitFlags registers CLI flags and env overrides.\nfunc InitFlags() {\n\t// Set default values\n\tServerPort = 44772\n\tServerLogLevel = 6\n\tServerAccessToken = \"\"\n\tApiGracefulShutdownTimeout = time.Second * 1\n\n\t// First, set default values from environment variables\n\tif jupyterFromEnv := os.Getenv(jupyterHostEnv); jupyterFromEnv != \"\" {\n\t\tif !strings.HasPrefix(jupyterFromEnv, \"http://\") && !strings.HasPrefix(jupyterFromEnv, \"https://\") {\n\t\t\tstdlog.Panic(\"Invalid JUPYTER_HOST format: must start with http:// or https://\")\n\t\t}\n\t\tJupyterServerHost = jupyterFromEnv\n\t}\n\n\tif jupyterTokenFromEnv := os.Getenv(jupyterTokenEnv); jupyterTokenFromEnv != \"\" {\n\t\tJupyterServerToken = jupyterTokenFromEnv\n\t}\n\n\t// Then define flags with current values as defaults\n\tflag.StringVar(&JupyterServerHost, \"jupyter-host\", JupyterServerHost, \"Jupyter server host address (e.g., http://localhost, http://192.168.1.100)\")\n\tflag.StringVar(&JupyterServerToken, \"jupyter-token\", JupyterServerToken, \"Jupyter server authentication token\")\n\tflag.IntVar(&ServerPort, \"port\", ServerPort, \"Server listening port (default: 44772)\")\n\tflag.IntVar(&ServerLogLevel, \"log-level\", ServerLogLevel, \"Server log level (0=LevelEmergency, 1=LevelAlert, 2=LevelCritical, 3=LevelError, 4=LevelWarning, 5=LevelNotice, 6=LevelInformational, 7=LevelDebug, default: 6)\")\n\tflag.StringVar(&ServerAccessToken, \"access-token\", ServerAccessToken, \"Server access token for API authentication\")\n\n\tif graceShutdownTimeout := os.Getenv(gracefulShutdownTimeoutEnv); graceShutdownTimeout != \"\" {\n\t\tduration, err := time.ParseDuration(graceShutdownTimeout)\n\t\tif err != nil {\n\t\t\tstdlog.Panicf(\"Failed to parse graceful shutdown timeout from env: %v\", err)\n\t\t}\n\t\tApiGracefulShutdownTimeout = duration\n\t}\n\n\tflag.DurationVar(&ApiGracefulShutdownTimeout, \"graceful-shutdown-timeout\", ApiGracefulShutdownTimeout, \"API graceful shutdown timeout duration (default: 3s)\")\n\n\t// Parse flags - these will override environment variables if provided\n\tflag.Parse()\n\n\t// Log final values\n\tlog.Info(\"Jupyter server host is: %s\", JupyterServerHost)\n\tlog.Info(\"Jupyter server token is: %s\", JupyterServerToken)\n}\n" }, { "path": "components/execd/pkg/jupyter/auth/auth.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage auth\n\nimport (\n\t\"fmt\"\n\t\"net/url\"\n)\n\n// Auth represents authentication configuration.\ntype Auth struct {\n\tToken string\n\tUsername string\n\tPassword string\n}\n\n// NewTokenAuth builds a token-based config.\nfunc NewTokenAuth(token string) *Auth {\n\treturn &Auth{\n\t\tToken: token,\n\t}\n}\n\n// NewBasicAuth builds a basic-auth config.\nfunc NewBasicAuth(username, password string) *Auth {\n\treturn &Auth{\n\t\tUsername: username,\n\t\tPassword: password,\n\t}\n}\n\n// Validate reports which auth mode is configured.\nfunc (a *Auth) Validate() string {\n\tif a.Token != \"\" {\n\t\treturn \"token\"\n\t}\n\tif a.Username != \"\" {\n\t\treturn \"basic\"\n\t}\n\treturn \"none\"\n}\n\n// AddAuthToURL appends token query parameters to the URL.\nfunc (a *Auth) AddAuthToURL(baseURL string) (string, error) {\n\tparsedURL, err := url.Parse(baseURL)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to parse URL: %w\", err)\n\t}\n\n\tquery := parsedURL.Query()\n\n\tif a.Token != \"\" {\n\t\tquery.Set(\"token\", a.Token)\n\t}\n\n\tparsedURL.RawQuery = query.Encode()\n\treturn parsedURL.String(), nil\n}\n" }, { "path": "components/execd/pkg/jupyter/auth/auth_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage auth\n\nimport (\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"testing\"\n)\n\nfunc TestTokenAuthentication(t *testing.T) {\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\ttoken := r.Header.Get(\"Authorization\")\n\t\texpectedToken := \"token test-token\"\n\t\tif token != expectedToken {\n\t\t\tw.WriteHeader(http.StatusUnauthorized)\n\t\t\treturn\n\t\t}\n\t\tw.WriteHeader(http.StatusOK)\n\t}))\n\tdefer server.Close()\n\n\tauth := NewAuth()\n\tauth.Token = \"test-token\"\n\n\tclient := NewClient(&http.Client{}, auth)\n\n\treq, err := http.NewRequest(\"GET\", server.URL, nil)\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to create request: %v\", err)\n\t}\n\n\tresp, err := client.Do(req)\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to send request: %v\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\tif resp.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"Expected status code %d, got %d\", http.StatusOK, resp.StatusCode)\n\t}\n}\n\nfunc TestBasicAuthentication(t *testing.T) {\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\tusername, password, ok := r.BasicAuth()\n\t\tif !ok || username != \"testuser\" || password != \"testpass\" {\n\t\t\tw.WriteHeader(http.StatusUnauthorized)\n\t\t\treturn\n\t\t}\n\t\tw.WriteHeader(http.StatusOK)\n\t}))\n\tdefer server.Close()\n\n\tauth := NewAuth()\n\tauth.Username = \"testuser\"\n\tauth.Password = \"testpass\"\n\n\tclient := NewClient(&http.Client{}, auth)\n\n\treq, err := http.NewRequest(\"GET\", server.URL, nil)\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to create request: %v\", err)\n\t}\n\n\tresp, err := client.Do(req)\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to send request: %v\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\tif resp.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"Expected status code %d, got %d\", http.StatusOK, resp.StatusCode)\n\t}\n}\n\nfunc TestAuthValidation(t *testing.T) {\n\temptyAuth := NewAuth()\n\tif emptyAuth.IsValid() {\n\t\tt.Error(\"Empty Auth should be invalid, but was determined to be valid\")\n\t}\n\n\ttokenAuth := NewAuth()\n\ttokenAuth.Token = \"test-token\"\n\tif !tokenAuth.IsValid() {\n\t\tt.Error(\"Auth with token should be valid, but was determined to be invalid\")\n\t}\n\n\tbasicAuth := NewAuth()\n\tbasicAuth.Username = \"testuser\"\n\tbasicAuth.Password = \"testpass\"\n\tif !basicAuth.IsValid() {\n\t\tt.Error(\"Auth with Basic Auth should be valid, but was determined to be invalid\")\n\t}\n\n\tinvalidBasicAuth := NewAuth()\n\tinvalidBasicAuth.Username = \"testuser\"\n\tif invalidBasicAuth.IsValid() {\n\t\tt.Error(\"Auth with only username and no password should be invalid, but was determined to be valid\")\n\t}\n\n\tmixedAuth := NewAuth()\n\tmixedAuth.Token = \"test-token\"\n\tmixedAuth.Username = \"testuser\"\n\tmixedAuth.Password = \"testpass\"\n\tif !mixedAuth.IsValid() {\n\t\tt.Error(\"Auth with both token and Basic Auth should be valid, but was determined to be invalid\")\n\t}\n}\n" }, { "path": "components/execd/pkg/jupyter/auth/client.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage auth\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\n// Client wraps http.Client and injects auth headers.\ntype Client struct {\n\thttpClient *http.Client\n\tauth *Auth\n}\n\n// NewClient creates a new authenticated HTTP client.\nfunc NewClient(httpClient *http.Client, auth *Auth) *Client {\n\treturn &Client{\n\t\thttpClient: httpClient,\n\t\tauth: auth,\n\t}\n}\n\n// Do sends an HTTP request and automatically adds authentication data.\nfunc (c *Client) Do(req *http.Request) (*http.Response, error) {\n\tif c.auth == nil {\n\t\treturn c.httpClient.Do(req)\n\t}\n\n\tif c.auth.Token != \"\" {\n\t\treq.Header.Set(\"Authorization\", fmt.Sprintf(\"token %s\", c.auth.Token))\n\t} else if c.auth.Username != \"\" {\n\t\treq.SetBasicAuth(c.auth.Username, c.auth.Password)\n\t}\n\n\treturn c.httpClient.Do(req)\n}\n\n// Get sends a GET request.\nfunc (c *Client) Get(url string) (*http.Response, error) {\n\treq, err := http.NewRequest(http.MethodGet, url, nil)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn c.Do(req)\n}\n\n// Post sends a POST request.\nfunc (c *Client) Post(url, contentType string, body io.Reader) (*http.Response, error) {\n\treq, err := http.NewRequest(http.MethodPost, url, body)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treq.Header.Set(\"Content-Type\", contentType)\n\treturn c.Do(req)\n}\n\n// Put sends a PUT request.\nfunc (c *Client) Put(url, contentType string, body io.Reader) (*http.Response, error) {\n\treq, err := http.NewRequest(http.MethodPut, url, body)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treq.Header.Set(\"Content-Type\", contentType)\n\treturn c.Do(req)\n}\n\n// Delete sends a DELETE request.\nfunc (c *Client) Delete(url string) (*http.Response, error) {\n\treq, err := http.NewRequest(http.MethodDelete, url, nil)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn c.Do(req)\n}\n" }, { "path": "components/execd/pkg/jupyter/auth/types.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage auth\n\nconst (\n\tAuthTypeNone = \"none\"\n\tAuthTypeToken = \"token\"\n\tAuthTypeBasic = \"basic\"\n\tAuthHeaderKey = \"Authorization\"\n\tAuthHeaderValuePrefix = \"token \"\n\tAuthURLParamKey = \"token\"\n)\n\n// NewAuth creates an empty authentication configuration.\nfunc NewAuth() *Auth {\n\treturn &Auth{}\n}\n\n// IsValid reports whether token or username/password are present.\nfunc (a *Auth) IsValid() bool {\n\treturn a.Token != \"\" || (a.Username != \"\" && a.Password != \"\")\n}\n\n// GetAuthType returns token/basic/none.\nfunc (a *Auth) GetAuthType() string {\n\treturn a.Validate()\n}\n" }, { "path": "components/execd/pkg/jupyter/client.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage jupyter\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"net/url\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/auth\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/kernel\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/session\"\n)\n\n// Client interacts with the Jupyter server.\ntype Client struct {\n\tBaseURL string\n\thttpClient *http.Client\n\tAuth *auth.Auth\n\tkernelClient *kernel.Client\n\tsessionClient *session.Client\n\texecuteClient *execute.Client\n\tauthClient *auth.Client\n}\n\ntype ClientOption func(*Client)\n\n// WithHTTPClient sets a custom HTTP client.\nfunc WithHTTPClient(client *http.Client) ClientOption {\n\treturn func(c *Client) {\n\t\tc.httpClient = client\n\t}\n}\n\n// WithToken configures the client with an authentication token.\nfunc WithToken(token string) ClientOption {\n\treturn func(c *Client) {\n\t\tc.Auth.Token = token\n\t}\n}\n\n// WithBasicAuth configures the client with basic authentication.\nfunc WithBasicAuth(username, password string) ClientOption {\n\treturn func(c *Client) {\n\t\tc.Auth.Username = username\n\t\tc.Auth.Password = password\n\t}\n}\n\n// NewClient creates a new Jupyter client instance.\nfunc NewClient(baseURL string, options ...ClientOption) *Client {\n\tclient := &Client{\n\t\tBaseURL: baseURL,\n\t\thttpClient: http.DefaultClient,\n\t\tAuth: auth.NewAuth(),\n\t}\n\n\tfor _, option := range options {\n\t\toption(client)\n\t}\n\n\tclient.authClient = auth.NewClient(client.httpClient, client.Auth)\n\n\tclient.kernelClient = kernel.NewClient(baseURL, client.httpClient)\n\tclient.sessionClient = session.NewClient(baseURL, client.httpClient)\n\tclient.executeClient = execute.NewClient(baseURL, client.authClient)\n\n\treturn client\n}\n\n// SetToken configures token authentication.\nfunc (c *Client) SetToken(token string) {\n\tc.Auth.Token = token\n}\n\n// SetBasicAuth configures username/password authentication.\nfunc (c *Client) SetBasicAuth(username, password string) {\n\tc.Auth.Username = username\n\tc.Auth.Password = password\n}\n\n// ValidateAuth quickly checks that some auth data is present.\nfunc (c *Client) ValidateAuth() (string, error) {\n\tauthType := c.Auth.Validate()\n\tif authType == \"none\" {\n\t\treturn \"error\", errors.New(\"no valid authentication information provided\")\n\t}\n\treturn \"ok\", nil\n}\n\n// GetKernelSpecs retrieves available kernel specifications.\nfunc (c *Client) GetKernelSpecs() (*kernel.KernelSpecs, error) {\n\treturn c.kernelClient.GetKernelSpecs()\n}\n\n// ListKernels retrieves all running kernels.\nfunc (c *Client) ListKernels() ([]*kernel.Kernel, error) {\n\treturn c.kernelClient.ListKernels()\n}\n\n// GetKernel retrieves information about a specific kernel.\nfunc (c *Client) GetKernel(kernelId string) (*kernel.Kernel, error) {\n\treturn c.kernelClient.GetKernel(kernelId)\n}\n\n// StartKernel starts a new kernel.\nfunc (c *Client) StartKernel(name string) (*kernel.Kernel, error) {\n\treturn c.kernelClient.StartKernel(name)\n}\n\n// RestartKernel restarts the specified kernel.\nfunc (c *Client) RestartKernel(kernelId string) (bool, error) {\n\treturn c.kernelClient.RestartKernel(kernelId)\n}\n\n// InterruptKernel interrupts the specified kernel.\nfunc (c *Client) InterruptKernel(kernelId string) error {\n\treturn c.kernelClient.InterruptKernel(kernelId)\n}\n\n// ShutdownKernel shuts down (and optionally restarts) the specified kernel.\nfunc (c *Client) ShutdownKernel(kernelId string, restart bool) error {\n\treturn c.kernelClient.ShutdownKernel(kernelId, restart)\n}\n\n// ListSessions retrieves active sessions.\nfunc (c *Client) ListSessions() ([]*session.Session, error) {\n\treturn c.sessionClient.ListSessions()\n}\n\n// GetSession retrieves information about a specific session.\nfunc (c *Client) GetSession(sessionId string) (*session.Session, error) {\n\treturn c.sessionClient.GetSession(sessionId)\n}\n\n// CreateSession creates a new session.\nfunc (c *Client) CreateSession(name, ipynb, kernel string) (*session.Session, error) {\n\treturn c.sessionClient.CreateSession(name, ipynb, kernel)\n}\n\n// ModifySession updates an existing session.\nfunc (c *Client) ModifySession(sessionId, name, path, kernel string) (*session.Session, error) {\n\treturn c.sessionClient.ModifySession(sessionId, name, path, kernel)\n}\n\n// DeleteSession deletes the specified session.\nfunc (c *Client) DeleteSession(sessionId string) error {\n\treturn c.sessionClient.DeleteSession(sessionId)\n}\n\n// ConnectToKernel establishes a websocket connection to the kernel.\nfunc (c *Client) ConnectToKernel(kernelId string) error {\n\tparsedURL, err := url.Parse(c.BaseURL)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"invalid base URL: %w\", err)\n\t}\n\n\tscheme := \"ws\"\n\tif parsedURL.Scheme == \"https\" {\n\t\tscheme = \"wss\"\n\t}\n\n\twsURL := fmt.Sprintf(\"%s://%s/api/kernels/%s/channels\", scheme, parsedURL.Host, kernelId)\n\n\tif c.Auth.Token != \"\" {\n\t\twsURL = fmt.Sprintf(\"%s?token=%s\", wsURL, c.Auth.Token)\n\t}\n\n\treturn c.executeClient.Connect(wsURL)\n}\n\n// DisconnectFromKernel closes the websocket connection.\nfunc (c *Client) DisconnectFromKernel(kernelId string) {\n\tc.executeClient.Disconnect()\n}\n\n// ExecuteCodeStream streams execution results into resultChan.\nfunc (c *Client) ExecuteCodeStream(kernelId, code string, resultChan chan *execute.ExecutionResult) error {\n\treturn c.executeClient.ExecuteCodeStream(code, resultChan)\n}\n\n// ExecuteCodeWithCallback processes execution events via callbacks.\nfunc (c *Client) ExecuteCodeWithCallback(code string, handler execute.CallbackHandler) error {\n\treturn c.executeClient.ExecuteCodeWithCallback(code, handler)\n}\n" }, { "path": "components/execd/pkg/jupyter/debug_integration_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage jupyter\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"net/http/httputil\"\n\t\"testing\"\n)\n\n// TestDebugServerIntegration logs real server interactions for debugging.\nfunc TestDebugServerIntegration(t *testing.T) {\n\tjupyterURL := getEnv(\"JUPYTER_URL\", \"\")\n\tjupyterToken := getEnv(\"JUPYTER_TOKEN\", \"\")\n\tif jupyterURL == \"\" || jupyterToken == \"\" {\n\t\tt.Skip(\"JUPYTER_URL and JUPYTER_TOKEN environment variables must be set to run this test\")\n\t}\n\n\tt.Logf(\"Connecting to Jupyter server: %s\", jupyterURL)\n\n\thttpClient := &http.Client{\n\t\tTransport: &debugTransport{t: t},\n\t}\n\n\tclient := NewClient(jupyterURL,\n\t\tWithToken(jupyterToken),\n\t\tWithHTTPClient(httpClient))\n\n\tt.Run(\"Validate Authentication\", func(t *testing.T) {\n\t\tt.Logf(\"Calling ValidateAuth...\")\n\t\tstatus, err := client.ValidateAuth()\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Authentication validation failed: %v\", err)\n\t\t}\n\t\tt.Logf(\"Authentication validation successful! Status: %s\", status)\n\t})\n\n\tt.Run(\"Get API Information\", func(t *testing.T) {\n\t\treq, err := http.NewRequest(\"GET\", fmt.Sprintf(\"%s/api\", jupyterURL), nil)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to create request: %v\", err)\n\t\t}\n\t\treq.Header.Set(\"Authorization\", fmt.Sprintf(\"Token %s\", jupyterToken))\n\n\t\tt.Logf(\"Sending request to /api endpoint...\")\n\t\tresp, err := httpClient.Do(req)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to send request: %v\", err)\n\t\t}\n\t\tdefer resp.Body.Close()\n\n\t\tif resp.StatusCode != http.StatusOK {\n\t\t\tt.Logf(\"API request returned non-200 status code: %d %s\", resp.StatusCode, resp.Status)\n\t\t} else {\n\t\t\tt.Logf(\"API request successful, status code: %d %s\", resp.StatusCode, resp.Status)\n\n\t\t\trespDump, err := httputil.DumpResponse(resp, true)\n\t\t\tif err != nil {\n\t\t\t\tt.Logf(\"Unable to dump response: %v\", err)\n\t\t\t} else {\n\t\t\t\tt.Logf(\"Response details:\\n%s\", string(respDump))\n\t\t\t}\n\t\t}\n\t})\n\n\tt.Run(\"Test Different Header Combinations\", func(t *testing.T) {\n\t\theaderSets := []map[string]string{\n\t\t\t{\n\t\t\t\t\"Authorization\": fmt.Sprintf(\"Token %s\", jupyterToken),\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"Authorization\": fmt.Sprintf(\"Token %s\", jupyterToken),\n\t\t\t\t\"X-XSRFToken\": jupyterToken[:16], // Use first 16 characters of token as XSRF token attempt\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"Authorization\": fmt.Sprintf(\"token %s\", jupyterToken), // lowercase token\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"Cookie\": fmt.Sprintf(\"_xsrf=%s; jupyter_token=%s\", jupyterToken[:16], jupyterToken),\n\t\t\t},\n\t\t}\n\n\t\tfor i, headers := range headerSets {\n\t\t\tt.Logf(\"Testing header combination #%d:\", i+1)\n\t\t\tfor k, v := range headers {\n\t\t\t\tt.Logf(\" %s: %s\", k, v)\n\t\t\t}\n\n\t\t\treq, err := http.NewRequest(\"GET\", fmt.Sprintf(\"%s/api/kernelspecs\", jupyterURL), nil)\n\t\t\tif err != nil {\n\t\t\t\tt.Fatalf(\"Failed to create request: %v\", err)\n\t\t\t}\n\n\t\t\tfor k, v := range headers {\n\t\t\t\treq.Header.Set(k, v)\n\t\t\t}\n\n\t\t\tt.Logf(\"Sending request to /api/kernelspecs endpoint...\")\n\t\t\tresp, err := httpClient.Do(req)\n\t\t\tif err != nil {\n\t\t\t\tt.Fatalf(\"Failed to send request: %v\", err)\n\t\t\t}\n\t\t\tdefer resp.Body.Close()\n\n\t\t\tt.Logf(\"Response status code: %d %s\", resp.StatusCode, resp.Status)\n\t\t\tif resp.StatusCode == http.StatusOK {\n\t\t\t\tt.Logf(\"Successfully found valid header combination!\")\n\n\t\t\t\trespDump, err := httputil.DumpResponse(resp, true)\n\t\t\t\tif err != nil {\n\t\t\t\t\tt.Logf(\"Unable to dump response: %v\", err)\n\t\t\t\t} else {\n\t\t\t\t\tmaxLen := 500\n\t\t\t\t\trespStr := string(respDump)\n\t\t\t\t\tif len(respStr) > maxLen {\n\t\t\t\t\t\tt.Logf(\"Response (truncated):\\n%s...\", respStr[:maxLen])\n\t\t\t\t\t} else {\n\t\t\t\t\t\tt.Logf(\"Response:\\n%s\", respStr)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t})\n}\n\n// debugTransport logs request and response dumps.\ntype debugTransport struct {\n\tt *testing.T\n}\n\nfunc (d *debugTransport) RoundTrip(req *http.Request) (*http.Response, error) {\n\treqDump, err := httputil.DumpRequestOut(req, true)\n\tif err != nil {\n\t\td.t.Logf(\"Unable to dump request: %v\", err)\n\t} else {\n\t\tmaxLen := 500\n\t\treqStr := string(reqDump)\n\t\tif len(reqStr) > maxLen {\n\t\t\td.t.Logf(\"Request (truncated):\\n%s...\", reqStr[:maxLen])\n\t\t} else {\n\t\t\td.t.Logf(\"Request:\\n%s\", reqStr)\n\t\t}\n\t}\n\n\tresp, err := http.DefaultTransport.RoundTrip(req)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\td.t.Logf(\"Response status: %d %s\", resp.StatusCode, resp.Status)\n\n\treturn resp, nil\n}\n" }, { "path": "components/execd/pkg/jupyter/execute/events.json", "content": "[\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_6\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.206377Z\",\n \"msg_type\": \"status\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e1df6eb2-f395e4906c9cecd23d97b548_7_2\",\n \"username\": \"username\",\n \"session\": \"e1df6eb2-f395e4906c9cecd23d97b548\",\n \"date\": \"2025-06-06T09:20:51.204953Z\",\n \"msg_type\": \"kernel_info_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {},\n \"content\": {\n \"execution_state\": \"busy\"\n },\n \"buffers\": [],\n \"channel\": \"iopub\"\n },\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_8\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.207083Z\",\n \"msg_type\": \"status\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e1df6eb2-f395e4906c9cecd23d97b548_7_1\",\n \"username\": \"username\",\n \"session\": \"e1df6eb2-f395e4906c9cecd23d97b548\",\n \"date\": \"2025-06-06T09:20:51.204866Z\",\n \"msg_type\": \"kernel_info_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {},\n \"content\": {\n \"execution_state\": \"idle\"\n },\n \"buffers\": [],\n \"channel\": \"iopub\"\n },\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_9\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.207169Z\",\n \"msg_type\": \"status\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e1df6eb2-f395e4906c9cecd23d97b548_7_2\",\n \"username\": \"username\",\n \"session\": \"e1df6eb2-f395e4906c9cecd23d97b548\",\n \"date\": \"2025-06-06T09:20:51.204953Z\",\n \"msg_type\": \"kernel_info_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {},\n \"content\": {\n \"execution_state\": \"idle\"\n },\n \"buffers\": [],\n \"channel\": \"iopub\"\n },\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_10\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.248234Z\",\n \"msg_type\": \"status\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0-1\",\n \"username\": \"go-client\",\n \"session\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0\",\n \"date\": \"2025-06-06T17:20:51+08:00\",\n \"msg_type\": \"execute_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {},\n \"content\": {\n \"execution_state\": \"busy\"\n },\n \"buffers\": [],\n \"channel\": \"iopub\"\n },\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_11\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.248481Z\",\n \"msg_type\": \"execute_input\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0-1\",\n \"username\": \"go-client\",\n \"session\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0\",\n \"date\": \"2025-06-06T17:20:51+08:00\",\n \"msg_type\": \"execute_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {},\n \"content\": {\n \"code\": \"print('Hello, Jupyter!')\\nresult = 2 + 2\\nresult\",\n \"execution_count\": 1\n },\n \"buffers\": [],\n \"channel\": \"iopub\"\n },\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_13\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.253641Z\",\n \"msg_type\": \"stream\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0-1\",\n \"username\": \"go-client\",\n \"session\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0\",\n \"date\": \"2025-06-06T17:20:51+08:00\",\n \"msg_type\": \"execute_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {},\n \"content\": {\n \"name\": \"stdout\",\n \"text\": \"Hello, Jupyter!\\n\"\n },\n \"buffers\": [],\n \"channel\": \"iopub\"\n },\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_12\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.251743Z\",\n \"msg_type\": \"execute_result\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0-1\",\n \"username\": \"go-client\",\n \"session\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0\",\n \"date\": \"2025-06-06T17:20:51+08:00\",\n \"msg_type\": \"execute_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {},\n \"content\": {\n \"data\": {\n \"text/plain\": \"4\"\n },\n \"metadata\": {},\n \"execution_count\": 1\n },\n \"buffers\": [],\n \"channel\": \"iopub\"\n },\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_14\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.255042Z\",\n \"msg_type\": \"execute_reply\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0-1\",\n \"username\": \"go-client\",\n \"session\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0\",\n \"date\": \"2025-06-06T17:20:51+08:00\",\n \"msg_type\": \"execute_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {\n \"dependencies_met\": true,\n \"engine\": \"d82231bb-94b0-4296-8372-2913351ee2a1\",\n \"started\": \"2025-06-06T09:20:51.248468Z\",\n \"status\": \"ok\"\n },\n \"content\": {\n \"status\": \"ok\",\n \"execution_count\": 1,\n \"user_expressions\": {},\n \"payload\": []\n },\n \"buffers\": [],\n \"channel\": \"shell\"\n },\n {\n \"header\": {\n \"msg_id\": \"e5e24851-db96ed91126b13f9b603136f_123284_15\",\n \"username\": \"username\",\n \"session\": \"e5e24851-db96ed91126b13f9b603136f\",\n \"date\": \"2025-06-06T09:20:51.255385Z\",\n \"msg_type\": \"status\",\n \"version\": \"5.3\"\n },\n \"parent_header\": {\n \"msg_id\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0-1\",\n \"username\": \"go-client\",\n \"session\": \"e8e7f0af-fdd9-4ea9-8d78-eab629b5c0f0\",\n \"date\": \"2025-06-06T17:20:51+08:00\",\n \"msg_type\": \"execute_request\",\n \"version\": \"5.3\"\n },\n \"metadata\": {},\n \"content\": {\n \"execution_state\": \"idle\"\n },\n \"buffers\": [],\n \"channel\": \"iopub\"\n }\n]\n" }, { "path": "components/execd/pkg/jupyter/execute/execute.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n// Package execute provides functionality for executing Jupyter kernel code via WebSocket\npackage execute\n\nimport (\n\t\"encoding/json\"\n\t\"errors\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"sync\"\n\t\"time\"\n\n\t\"github.com/google/uuid\"\n\t\"github.com/gorilla/websocket\"\n)\n\n// HTTPClient defines the HTTP client interface\ntype HTTPClient interface {\n\tDo(req *http.Request) (*http.Response, error)\n}\n\n// Client is the client for code execution\ntype Client struct {\n\t// Internal HTTP client for sending HTTP requests\n\thttpClient HTTPClient\n\n\t// WebSocket connection\n\tconn *websocket.Conn\n\n\t// Message handler mappings\n\thandlers map[MessageType]func(*Message)\n\n\t// Session ID\n\tsession string\n\n\t// Message ID counter\n\tmsgCounter int\n\n\t// Mutex for protecting concurrent access\n\tmu sync.Mutex\n\n\t// WebSocket URL for kernel connection\n\twsURL string\n}\n\n// NewClient creates a new code execution client\nfunc NewClient(baseURL string, httpClient HTTPClient) *Client {\n\treturn &Client{\n\t\thttpClient: httpClient,\n\t\thandlers: make(map[MessageType]func(*Message)),\n\t\tsession: uuid.New().String(),\n\t\tmsgCounter: 0,\n\t}\n}\n\n// Connect connects to the WebSocket of the specified kernel\nfunc (c *Client) Connect(wsURL string) error {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\t// Save WebSocket URL\n\tc.wsURL = wsURL\n\n\t// Connect to WebSocket\n\tconn, resp, err := websocket.DefaultDialer.Dial(wsURL, nil)\n\tif resp != nil && err != nil {\n\t\tresp.Body.Close()\n\t}\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to connect to kernel: %w\", err)\n\t}\n\tc.conn = conn\n\n\t// Register default message handlers\n\tc.registerDefaultHandlers()\n\n\t// Start message receiving goroutine\n\tgo c.receiveMessages()\n\n\treturn nil\n}\n\n// Disconnect disconnects the WebSocket connection to the kernel\nfunc (c *Client) Disconnect() {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\tif c.conn != nil {\n\t\tc.conn.Close()\n\t\tc.conn = nil\n\t}\n}\n\n// IsConnected checks if connected to the kernel\nfunc (c *Client) IsConnected() bool {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\treturn c.conn != nil\n}\n\n// ExecuteCodeStream executes code in streaming mode, sending results to the provided channel\nfunc (c *Client) ExecuteCodeStream(code string, resultChan chan *ExecutionResult) error {\n\tif !c.IsConnected() {\n\t\treturn errors.New(\"not connected to kernel, please call Connect method\")\n\t}\n\n\t// record start time\n\tstartTime := time.Now()\n\n\t// prepare execution request\n\tmsgID := c.nextMessageID()\n\trequest := &ExecuteRequest{\n\t\tCode: code,\n\t\tSilent: false,\n\t\tStoreHistory: true,\n\t\tUserExpressions: make(map[string]string),\n\t\tAllowStdin: false,\n\t\tStopOnError: true,\n\t}\n\n\t// serialize request content\n\tcontent, err := json.Marshal(request)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to serialize request: %w\", err)\n\t}\n\n\t// create message\n\tmsg := &Message{\n\t\tHeader: Header{\n\t\t\tMessageID: msgID,\n\t\t\tUsername: \"go-client\",\n\t\t\tSession: c.session,\n\t\t\tDate: time.Now().Format(time.RFC3339),\n\t\t\tMessageType: string(MsgExecuteRequest),\n\t\t\tVersion: \"5.3\",\n\t\t},\n\t\tParentHeader: Header{},\n\t\tMetadata: make(map[string]interface{}),\n\t\tContent: content,\n\t\tChannel: \"shell\",\n\t}\n\n\t// Create result object\n\tresult := &ExecutionResult{\n\t\tStatus: \"ok\",\n\t\tStream: make([]*StreamOutput, 0),\n\t\tExecutionTime: 0,\n\t}\n\n\t// Register temporary handler to receive execution result\n\tvar executeDone bool\n\tvar executeMutex sync.Mutex\n\tvar executeResult *ExecuteResult\n\n\t// Create mutex to protect result object\n\tvar resultMutex sync.Mutex\n\n\t// Clear temporary handlers\n\tc.clearTemporaryHandlers()\n\n\tc.registerHandler(MsgExecuteReply, func(msg *Message) {\n\t\tvar execReply ExecuteReply\n\t\tif err := json.Unmarshal(msg.Content, &execReply); err != nil {\n\t\t\treturn\n\t\t}\n\n\t\tresultMutex.Lock()\n\t\tresult.ExecutionCount = execReply.ExecutionCount\n\t\tif execReply.EName != \"\" {\n\t\t\tresult.Error = &execReply.ErrorOutput\n\t\t}\n\t\tresultMutex.Unlock()\n\t})\n\n\t// register execution result handler\n\tc.registerHandler(MsgExecuteResult, func(msg *Message) {\n\t\tvar execResult ExecuteResult\n\t\tif err := json.Unmarshal(msg.Content, &execResult); err != nil {\n\t\t\treturn\n\t\t}\n\n\t\texecuteMutex.Lock()\n\t\texecuteResult = &execResult\n\t\texecuteMutex.Unlock()\n\n\t\tresultMutex.Lock()\n\t\tresult.ExecutionCount = execResult.ExecutionCount\n\n\t\tnotify := &ExecutionResult{}\n\t\tnotify.ExecutionCount = executeResult.ExecutionCount\n\t\tnotify.ExecutionData = executeResult.Data\n\n\t\tresultChan <- notify\n\t\tresultMutex.Unlock()\n\t})\n\n\t// Register stream output handler\n\tc.registerHandler(MsgStream, func(msg *Message) {\n\t\tvar stream StreamOutput\n\t\tif err := json.Unmarshal(msg.Content, &stream); err != nil {\n\t\t\treturn\n\t\t}\n\n\t\tresultMutex.Lock()\n\t\tresult.Stream = append(result.Stream, &stream)\n\n\t\tnotify := &ExecutionResult{}\n\t\tnotify.Stream = []*StreamOutput{&stream}\n\n\t\tresultChan <- notify\n\t\tresultMutex.Unlock()\n\t})\n\n\t// register error handler\n\tc.registerHandler(MsgError, func(msg *Message) {\n\t\tvar errOutput ErrorOutput\n\t\tif err := json.Unmarshal(msg.Content, &errOutput); err != nil {\n\t\t\treturn\n\t\t}\n\n\t\tresultMutex.Lock()\n\t\tresult.Status = \"error\"\n\t\tresult.Error = &errOutput\n\n\t\tnotify := &ExecutionResult{}\n\t\tnotify.Error = &errOutput\n\t\tnotify.Status = \"error\"\n\n\t\tresultChan <- notify\n\t\tresultMutex.Unlock()\n\t})\n\n\t// register status handler\n\tc.registerHandler(MsgStatus, func(msg *Message) {\n\t\tvar status StatusUpdate\n\t\tif err := json.Unmarshal(msg.Content, &status); err != nil {\n\t\t\treturn\n\t\t}\n\n\t\tif status.ExecutionState == StateIdle {\n\t\t\texecuteMutex.Lock()\n\n\t\t\t// Check whether execution can be completed\n\t\t\tif !executeDone {\n\t\t\t\texecuteDone = true\n\t\t\t\tgo func() {\n\t\t\t\t\t// calculate execution time\n\t\t\t\t\tresultMutex.Lock()\n\t\t\t\t\tresult.ExecutionTime = time.Since(startTime)\n\n\t\t\t\t\t// Send final result\n\t\t\t\t\tnotify := &ExecutionResult{}\n\t\t\t\t\tnotify.ExecutionTime = result.ExecutionTime\n\n\t\t\t\t\tresultChan <- notify\n\t\t\t\t\tresultMutex.Unlock()\n\n\t\t\t\t\tfor result.ExecutionCount <= 0 && result.Error == nil {\n\t\t\t\t\t\ttime.Sleep(300 * time.Millisecond)\n\t\t\t\t\t}\n\n\t\t\t\t\t// Close result channel\n\t\t\t\t\tclose(resultChan)\n\t\t\t\t}()\n\t\t\t}\n\t\t\texecuteMutex.Unlock()\n\t\t}\n\t})\n\n\t// send execution request\n\tc.mu.Lock()\n\terr = c.conn.WriteJSON(msg)\n\tc.mu.Unlock()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to send execution request: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// ExecuteCodeWithCallback executes code using callback functions\nfunc (c *Client) ExecuteCodeWithCallback(code string, handler CallbackHandler) error {\n\tif !c.IsConnected() {\n\t\treturn errors.New(\"not connected to kernel, please call Connect method\")\n\t}\n\n\t// prepare execution request\n\tmsgID := c.nextMessageID()\n\trequest := &ExecuteRequest{\n\t\tCode: code,\n\t\tSilent: false,\n\t\tStoreHistory: true,\n\t\tUserExpressions: make(map[string]string),\n\t\tAllowStdin: false,\n\t\tStopOnError: true,\n\t}\n\n\t// serialize request content\n\tcontent, err := json.Marshal(request)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to serialize request: %w\", err)\n\t}\n\n\t// create message\n\tmsg := &Message{\n\t\tHeader: Header{\n\t\t\tMessageID: msgID,\n\t\t\tUsername: \"go-client\",\n\t\t\tSession: c.session,\n\t\t\tDate: time.Now().Format(time.RFC3339),\n\t\t\tMessageType: string(MsgExecuteRequest),\n\t\t\tVersion: \"5.3\",\n\t\t},\n\t\tParentHeader: Header{},\n\t\tMetadata: make(map[string]interface{}),\n\t\tContent: content,\n\t\tChannel: \"shell\",\n\t}\n\n\t// register execution result handler\n\tif handler.OnExecuteResult != nil {\n\t\tc.registerHandler(MsgExecuteResult, func(msg *Message) {\n\t\t\tvar execResult ExecuteResult\n\t\t\tif err := json.Unmarshal(msg.Content, &execResult); err != nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\t// calls callback functions\n\t\t\thandler.OnExecuteResult(&execResult)\n\t\t})\n\t}\n\n\t// Register stream output handler\n\tif handler.OnStream != nil {\n\t\tc.registerHandler(MsgStream, func(msg *Message) {\n\t\t\tvar stream StreamOutput\n\t\t\tif err := json.Unmarshal(msg.Content, &stream); err != nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\t// calls callback functions\n\t\t\thandler.OnStream(&stream)\n\t\t})\n\t}\n\n\t// Register display data handler\n\tif handler.OnDisplayData != nil {\n\t\tc.registerHandler(MsgDisplayData, func(msg *Message) {\n\t\t\tvar display DisplayData\n\t\t\tif err := json.Unmarshal(msg.Content, &display); err != nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\t// calls callback functions\n\t\t\thandler.OnDisplayData(&display)\n\t\t})\n\t}\n\n\t// register error handler\n\tif handler.OnError != nil {\n\t\tc.registerHandler(MsgError, func(msg *Message) {\n\t\t\tvar errOutput ErrorOutput\n\t\t\tif err := json.Unmarshal(msg.Content, &errOutput); err != nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\t// calls callback functions\n\t\t\thandler.OnError(&errOutput)\n\t\t})\n\t}\n\n\t// register status handler\n\tif handler.OnStatus != nil {\n\t\tc.registerHandler(MsgStatus, func(msg *Message) {\n\t\t\tvar status StatusUpdate\n\t\t\tif err := json.Unmarshal(msg.Content, &status); err != nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\t// calls callback functions\n\t\t\thandler.OnStatus(&status)\n\t\t})\n\t}\n\n\t// send execution request\n\tc.mu.Lock()\n\terr = c.conn.WriteJSON(msg)\n\tc.mu.Unlock()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to send execution request: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// Register default message handlers\nfunc (c *Client) registerDefaultHandlers() {\n\t// default message handlers can be registered here\n}\n\n// Register temporary message handler\nfunc (c *Client) registerHandler(msgType MessageType, handler func(*Message)) {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\tc.handlers[msgType] = handler\n}\n\n// Clear temporary message handlers\nfunc (c *Client) clearTemporaryHandlers() {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\tc.handlers = make(map[MessageType]func(*Message))\n\tc.registerDefaultHandlers()\n}\n\n// Receive WebSocket messages\nfunc (c *Client) receiveMessages() {\n\tfor {\n\t\tc.mu.Lock()\n\t\tconn := c.conn\n\t\tc.mu.Unlock()\n\n\t\tif conn == nil {\n\t\t\tbreak\n\t\t}\n\n\t\t// Receive message\n\t\tvar msg Message\n\t\terr := conn.ReadJSON(&msg)\n\t\tif err != nil {\n\t\t\t// connection may already be closed\n\t\t\tbreak\n\t\t}\n\n\t\t// Process message\n\t\tc.handleMessage(&msg)\n\t}\n}\n\n// Handle received messages\nfunc (c *Client) handleMessage(msg *Message) {\n\t// Extract message type\n\tmsgType := MessageType(msg.Header.MessageType)\n\n\t// call the corresponding handler\n\tc.mu.Lock()\n\thandler, ok := c.handlers[msgType]\n\tc.mu.Unlock()\n\n\tif ok && handler != nil {\n\t\thandler(msg)\n\t}\n}\n\n// generate next messageID\nfunc (c *Client) nextMessageID() string {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\tc.msgCounter++\n\treturn fmt.Sprintf(\"%s-%d\", c.session, c.msgCounter)\n}\n" }, { "path": "components/execd/pkg/jupyter/execute/execute_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage execute\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"strings\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/gorilla/websocket\"\n)\n\n// Create WebSocket test server\nfunc createTestServer(t *testing.T, handleFunc func(conn *websocket.Conn)) *httptest.Server {\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\t// Validate request path\n\t\tif !strings.HasPrefix(r.URL.Path, \"/api/kernels/\") {\n\t\t\tt.Errorf(\"expected path to start with '/api/kernels/', got '%s'\", r.URL.Path)\n\t\t}\n\t\tif !strings.HasSuffix(r.URL.Path, \"/channels\") {\n\t\t\tt.Errorf(\"expected path to end with '/channels', got '%s'\", r.URL.Path)\n\t\t}\n\n\t\t// Upgrade HTTP connection to WebSocket\n\t\tupgrader := websocket.Upgrader{\n\t\t\tCheckOrigin: func(r *http.Request) bool { return true },\n\t\t}\n\t\tconn, err := upgrader.Upgrade(w, r, nil)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"failed to upgrade to WebSocket: %v\", err)\n\t\t}\n\t\tdefer conn.Close()\n\n\t\t// Handle WebSocket connection\n\t\thandleFunc(conn)\n\t}))\n\n\treturn server\n}\n\n// Test streaming code execution\nfunc TestExecuteCodeStream(t *testing.T) {\n\t// Spin up mock WebSocket server\n\tserver := createTestServer(t, func(conn *websocket.Conn) {\n\t\t// Read execution request\n\t\tvar executeRequest Message\n\t\terr := conn.ReadJSON(&executeRequest)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"failed to read execution request: %v\", err)\n\t\t}\n\n\t\t// Send multiple stream messages\n\t\tfor i := 0; i < 3; i++ {\n\t\t\tstreamContent, _ := json.Marshal(StreamOutput{\n\t\t\t\tName: StreamStdout,\n\t\t\t\tText: \"Line \" + string(rune('0'+i)) + \"\\n\",\n\t\t\t})\n\n\t\t\tstreamMsg := Message{\n\t\t\t\tHeader: Header{\n\t\t\t\t\tMessageID: \"stream-msg-id-\" + string(rune('0'+i)),\n\t\t\t\t\tSession: executeRequest.Header.Session,\n\t\t\t\t\tMessageType: string(MsgStream),\n\t\t\t\t},\n\t\t\t\tParentHeader: executeRequest.Header,\n\t\t\t\tContent: json.RawMessage(streamContent),\n\t\t\t}\n\t\t\tconn.WriteJSON(streamMsg)\n\t\t\ttime.Sleep(100 * time.Millisecond)\n\t\t}\n\n\t\t// Send execution result\n\t\tresultContent, _ := json.Marshal(ExecuteResult{\n\t\t\tExecutionCount: 1,\n\t\t\tData: map[string]interface{}{\n\t\t\t\t\"text/plain\": \"Completed\",\n\t\t\t},\n\t\t\tMetadata: map[string]interface{}{},\n\t\t})\n\n\t\texecuteResultMsg := Message{\n\t\t\tHeader: Header{\n\t\t\t\tMessageID: \"result-msg-id\",\n\t\t\t\tSession: executeRequest.Header.Session,\n\t\t\t\tMessageType: string(MsgExecuteResult),\n\t\t\t},\n\t\t\tParentHeader: executeRequest.Header,\n\t\t\tContent: json.RawMessage(resultContent),\n\t\t}\n\t\tconn.WriteJSON(executeResultMsg)\n\n\t\t// Send status message\n\t\tstatusContent, _ := json.Marshal(StatusUpdate{\n\t\t\tExecutionState: StateIdle,\n\t\t})\n\n\t\tstatusMsg := Message{\n\t\t\tHeader: Header{\n\t\t\t\tMessageID: \"status-msg-id\",\n\t\t\t\tSession: executeRequest.Header.Session,\n\t\t\t\tMessageType: string(MsgStatus),\n\t\t\t},\n\t\t\tParentHeader: executeRequest.Header,\n\t\t\tContent: json.RawMessage(statusContent),\n\t\t}\n\t\tconn.WriteJSON(statusMsg)\n\t})\n\tdefer server.Close()\n\n\t// Convert HTTP URL to WebSocket URL\n\twsURL := \"ws\" + strings.TrimPrefix(server.URL, \"http\") + \"/api/kernels/test-kernel-id/channels\"\n\n\t// Create executor client\n\texecutor := NewExecutor(wsURL, nil)\n\n\t// Connect to WebSocket\n\terr := executor.Connect()\n\tif err != nil {\n\t\tt.Fatalf(\"failed to connect to WebSocket: %v\", err)\n\t}\n\tdefer executor.Disconnect()\n\n\t// Execute code in streaming mode\n\tresultChan := make(chan *ExecutionResult, 10)\n\terr = executor.ExecuteCodeStream(\"for i in range(3):\\n print(f'Line {i}')\", resultChan)\n\tif err != nil {\n\t\tt.Fatalf(\"failed to start streaming execution: %v\", err)\n\t}\n\n\t// Receive and verify stream results\n\tresultCount := 0\n\tfor result := range resultChan {\n\t\tif result == nil {\n\t\t\tbreak\n\t\t}\n\t\tresultCount++\n\t}\n\n\t// Should receive at least 4 results (3 stream outputs + 1 final result)\n\tif resultCount < 4 {\n\t\tt.Errorf(\"expected at least 4 results, got %d\", resultCount)\n\t}\n}\n" }, { "path": "components/execd/pkg/jupyter/execute/executor.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage execute\n\n// Executor is the interface for code execution\ntype Executor struct {\n\t// Internal client\n\tclient *Client\n\t// WebSocket URL\n\twsURL string\n}\n\n// NewExecutor creates a new code executor\nfunc NewExecutor(wsURL string, httpClient HTTPClient) *Executor {\n\tclient := NewClient(\"\", httpClient)\n\treturn &Executor{\n\t\tclient: client,\n\t\twsURL: wsURL,\n\t}\n}\n\n// Connect connects to the kernel\nfunc (e *Executor) Connect() error {\n\treturn e.client.Connect(e.wsURL)\n}\n\n// Disconnect disconnects from the kernel\nfunc (e *Executor) Disconnect() {\n\te.client.Disconnect()\n}\n\n// ExecuteCodeStream executes code in streaming mode, sending results to the provided channel\nfunc (e *Executor) ExecuteCodeStream(code string, resultChan chan *ExecutionResult) error {\n\treturn e.client.ExecuteCodeStream(code, resultChan)\n}\n\n// ExecuteCodeWithCallback executes code using callback functions\nfunc (e *Executor) ExecuteCodeWithCallback(code string, handler CallbackHandler) error {\n\treturn e.client.ExecuteCodeWithCallback(code, handler)\n}\n" }, { "path": "components/execd/pkg/jupyter/execute/types.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n// Package execute provides functionality for executing Jupyter kernel code via WebSocket\npackage execute\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"strings\"\n\t\"time\"\n)\n\n// MessageType represents Jupyter message types\ntype MessageType string\n\nconst (\n\t// MsgExecuteRequest requests code execution\n\tMsgExecuteRequest MessageType = \"execute_request\"\n\n\t// MsgExecuteInput represents the input code\n\tMsgExecuteInput MessageType = \"execute_input\"\n\n\t// MsgExecuteResult represents execution results\n\tMsgExecuteResult MessageType = \"execute_result\"\n\n\t// MsgDisplayData represents data to be displayed\n\tMsgDisplayData MessageType = \"display_data\"\n\n\t// MsgStream represents stream output (stdout/stderr)\n\tMsgStream MessageType = \"stream\"\n\n\t// MsgError represents errors during execution\n\tMsgError MessageType = \"error\"\n\n\t// MsgStatus represents kernel status updates\n\tMsgStatus MessageType = \"status\"\n\n\t// MsgClearOutput represents clearing output\n\tMsgClearOutput MessageType = \"clear_output\"\n\n\t// MsgComm represents communication messages\n\tMsgComm MessageType = \"comm\"\n\n\t// MsgCommOpen represents opening communication\n\tMsgCommOpen MessageType = \"comm_open\"\n\n\t// MsgCommClose represents closing communication\n\tMsgCommClose MessageType = \"comm_close\"\n\n\t// MsgCommMsg representscommunication message content\n\tMsgCommMsg MessageType = \"comm_msg\"\n\n\t// MsgKernelInfo represents kernel information request\n\tMsgKernelInfo MessageType = \"kernel_info_request\"\n\n\t// MsgKernelInfoReply represents kernel information response\n\tMsgKernelInfoReply MessageType = \"kernel_info_reply\"\n\n\tMsgExecuteReply MessageType = \"execute_reply\"\n)\n\n// StreamType representsoutput stream type\ntype StreamType string\n\nconst (\n\t// StreamStdout represents standard output stream\n\tStreamStdout StreamType = \"stdout\"\n\n\t// StreamStderr representsstandard error stream\n\tStreamStderr StreamType = \"stderr\"\n)\n\n// ExecutionState represents kernel execution state\ntype ExecutionState string\n\nconst (\n\t// StateIdle representskernel is idle\n\tStateIdle ExecutionState = \"idle\"\n\n\t// StateBusy representskernel is busy\n\tStateBusy ExecutionState = \"busy\"\n\n\t// StateStarting representskernel is starting\n\tStateStarting ExecutionState = \"starting\"\n)\n\n// Header defines Jupyter message header\ntype Header struct {\n\t// MessageID is the unique identifier of the message\n\tMessageID string `json:\"msg_id\"`\n\n\t// Username is the username sending the message\n\tUsername string `json:\"username\"`\n\n\t// Session is the session identifier\n\tSession string `json:\"session\"`\n\n\t// Date is the timestamp when the message was sent\n\tDate string `json:\"date\"`\n\n\t// MessageType is the type of the message\n\tMessageType string `json:\"msg_type\"`\n\n\t// Version is the version of the message protocol\n\tVersion string `json:\"version\"`\n}\n\n// Message defines the basic structure of Jupyter messages\ntype Message struct {\n\t// Header is the message header\n\tHeader Header `json:\"header\"`\n\n\t// ParentHeader is the parent message header, used to track requests and responses\n\tParentHeader Header `json:\"parent_header\"`\n\n\t// Metadata is the metadata related to the message\n\tMetadata map[string]interface{} `json:\"metadata\"`\n\n\t// Content is the actual content of the message\n\tContent json.RawMessage `json:\"content\"`\n\n\t// Buffers is the binary buffer\n\tBuffers [][]byte `json:\"buffers\"`\n\n\t// Channel is the channel of the message\n\tChannel string `json:\"channel\"`\n}\n\n// ExecuteRequest defines the request content for code execution\ntype ExecuteRequest struct {\n\t// Code is the code to execute\n\tCode string `json:\"code\"`\n\n\t// Silent represents whether to execute in silent mode\n\tSilent bool `json:\"silent\"`\n\n\t// StoreHistory represents whether to store execution history\n\tStoreHistory bool `json:\"store_history\"`\n\n\t// UserExpressions contains expressions to evaluate in the execution context\n\tUserExpressions map[string]string `json:\"user_expressions\"`\n\n\t// AllowStdin represents whether to allow reading from standard input\n\tAllowStdin bool `json:\"allow_stdin\"`\n\n\t// StopOnError represents whether to stop execution when an error is encountered\n\tStopOnError bool `json:\"stop_on_error\"`\n}\n\n// StreamOutput represents stream output content\ntype StreamOutput struct {\n\t// Name is the stream name (stdout or stderr)\n\tName StreamType `json:\"name\"`\n\n\t// Text is the text content of the stream\n\tText string `json:\"text\"`\n}\n\n// ExecuteResult represents the result of code execution\ntype ExecuteResult struct {\n\t// ExecutionCount is the execution counter value\n\tExecutionCount int `json:\"execution_count\"`\n\n\t// Data contains result data in different formats\n\tData map[string]interface{} `json:\"data\"`\n\n\t// Metadata is the metadata related to the result\n\tMetadata map[string]interface{} `json:\"metadata\"`\n}\n\ntype ExecuteReply struct {\n\t// ExecutionCount is the execution counter value\n\tExecutionCount int `json:\"execution_count\"`\n\n\tStatus string `json:\"status\"`\n\n\tErrorOutput `json:\",inline\"`\n}\n\n// DisplayData representsdata to display\ntype DisplayData struct {\n\t// Data contains display data in different formats\n\tData map[string]interface{} `json:\"data\"`\n\n\t// Metadata is the metadata related to display data\n\tMetadata map[string]interface{} `json:\"metadata\"`\n}\n\n// ErrorOutput representserrors during execution\ntype ErrorOutput struct {\n\t// EName is the name of the error\n\tEName string `json:\"ename\"`\n\n\t// EValue is the value of the error\n\tEValue string `json:\"evalue\"`\n\n\t// Traceback is the traceback of the error\n\tTraceback []string `json:\"traceback\"`\n}\n\nfunc (e *ErrorOutput) String() string {\n\treturn fmt.Sprintf(`\nError: %s\nValue: %s\nTraceback: %s\n`, e.EName, e.EValue, strings.Join(e.Traceback, \"\\n\"))\n}\n\n// StatusUpdate represents kernel status update\ntype StatusUpdate struct {\n\t// ExecutionState is the execution state of the kernel\n\tExecutionState ExecutionState `json:\"execution_state\"`\n}\n\n// ExecutionResult represents the complete result of code execution\ntype ExecutionResult struct {\n\t// Status represents the status of execution\n\tStatus string `json:\"status\"`\n\n\t// ExecutionCount is the execution counter value\n\tExecutionCount int `json:\"execution_count\"`\n\n\t// Stream contains all stream output\n\tStream []*StreamOutput `json:\"stream\"`\n\n\t// Error contains errors during execution (if any)\n\tError *ErrorOutput `json:\"error\"`\n\n\t// ExecutionTime is the total time of code execution\n\tExecutionTime time.Duration `json:\"execution_time\"`\n\n\t// ExecutionData\n\tExecutionData map[string]interface{} `json:\"execution_data\"`\n}\n\n// CallbackHandler defines callback functions for handling different types of messages\ntype CallbackHandler struct {\n\t// OnExecuteResult handles execution result messages\n\tOnExecuteResult func(*ExecuteResult)\n\n\t// OnStream handles stream output messages\n\tOnStream func(...*StreamOutput)\n\n\t// OnDisplayData handles display data messages\n\tOnDisplayData func(*DisplayData)\n\n\t// OnError handles error messages\n\tOnError func(*ErrorOutput)\n\n\t// OnStatus handles status update messages\n\tOnStatus func(*StatusUpdate)\n}\n" }, { "path": "components/execd/pkg/jupyter/execute/zz_generated.deepcopy.go", "content": "//go:build !ignore_autogenerated\n\n/*\nCopyright 2022.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n*/\n\n// Code generated by controller-gen. DO NOT EDIT.\n\npackage execute\n\n// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.\nfunc (in *ErrorOutput) DeepCopyInto(out *ErrorOutput) {\n\t*out = *in\n\tif in.Traceback != nil {\n\t\tin, out := &in.Traceback, &out.Traceback\n\t\t*out = make([]string, len(*in))\n\t\tcopy(*out, *in)\n\t}\n}\n\n// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ErrorOutput.\nfunc (in *ErrorOutput) DeepCopy() *ErrorOutput {\n\tif in == nil {\n\t\treturn nil\n\t}\n\tout := new(ErrorOutput)\n\tin.DeepCopyInto(out)\n\treturn out\n}\n\n// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.\nfunc (in *ExecutionResult) DeepCopyInto(out *ExecutionResult) {\n\t*out = *in\n\tif in.Stream != nil {\n\t\tin, out := &in.Stream, &out.Stream\n\t\t*out = make([]*StreamOutput, len(*in))\n\t\tfor i := range *in {\n\t\t\tif (*in)[i] != nil {\n\t\t\t\tin, out := &(*in)[i], &(*out)[i]\n\t\t\t\t*out = new(StreamOutput)\n\t\t\t\t**out = **in\n\t\t\t}\n\t\t}\n\t}\n\tif in.Error != nil {\n\t\tin, out := &in.Error, &out.Error\n\t\t*out = new(ErrorOutput)\n\t\t(*in).DeepCopyInto(*out)\n\t}\n}\n\n// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ExecutionResult.\nfunc (in *ExecutionResult) DeepCopy() *ExecutionResult {\n\tif in == nil {\n\t\treturn nil\n\t}\n\tout := new(ExecutionResult)\n\tin.DeepCopyInto(out)\n\treturn out\n}\n\n// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.\nfunc (in *StreamOutput) DeepCopyInto(out *StreamOutput) {\n\t*out = *in\n}\n\n// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new StreamOutput.\nfunc (in *StreamOutput) DeepCopy() *StreamOutput {\n\tif in == nil {\n\t\treturn nil\n\t}\n\tout := new(StreamOutput)\n\tin.DeepCopyInto(out)\n\treturn out\n}\n" }, { "path": "components/execd/pkg/jupyter/integration_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage jupyter\n\nimport (\n\t\"encoding/json\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"strings\"\n\t\"testing\"\n\n\t\"github.com/gorilla/websocket\"\n)\n\n// Test integration flow: authentication -> get kernel specs -> create session -> execute code -> close session\nfunc TestIntegrationFlow(t *testing.T) {\n\t// Create mock HTTP server\n\thttpServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\t// Handle authentication validation request\n\t\tif r.URL.Path == \"/api/status\" {\n\t\t\t// Check authentication token\n\t\t\tauth := r.Header.Get(\"Authorization\")\n\t\t\tif auth != \"token test-token\" {\n\t\t\t\tw.WriteHeader(http.StatusUnauthorized)\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\t// Return status information\n\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\tw.Write([]byte(`{\"status\": \"ok\"}`))\n\t\t\treturn\n\t\t}\n\n\t\t// Handle kernel specs request\n\t\tif r.URL.Path == \"/api/kernelspecs\" {\n\t\t\t// Return kernel specs\n\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\tw.Write([]byte(`{\n\t\t\t\t\"default\": \"python3\",\n\t\t\t\t\"kernelspecs\": {\n\t\t\t\t\t\"python3\": {\n\t\t\t\t\t\t\"name\": \"python3\",\n\t\t\t\t\t\t\"display_name\": \"Python 3\",\n\t\t\t\t\t\t\"language\": \"python\"\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}`))\n\t\t\treturn\n\t\t}\n\n\t\t// Handle session-related requests\n\t\tif r.URL.Path == \"/api/sessions\" {\n\t\t\tif r.Method == http.MethodGet {\n\t\t\t\t// List sessions\n\t\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\t\tw.Write([]byte(`[{\n\t\t\t\t\t\"id\": \"test-session-id\",\n\t\t\t\t\t\"path\": \"/path/to/notebook.ipynb\",\n\t\t\t\t\t\"name\": \"Test Session\",\n\t\t\t\t\t\"type\": \"notebook\",\n\t\t\t\t\t\"kernel\": {\n\t\t\t\t\t\t\"id\": \"test-kernel-id\",\n\t\t\t\t\t\t\"name\": \"python3\"\n\t\t\t\t\t}\n\t\t\t\t}]`))\n\t\t\t\treturn\n\t\t\t} else if r.Method == http.MethodPost {\n\t\t\t\t// Create session\n\t\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\t\tw.WriteHeader(http.StatusCreated)\n\t\t\t\tw.Write([]byte(`{\n\t\t\t\t\t\"id\": \"test-session-id\",\n\t\t\t\t\t\"path\": \"/path/to/notebook.ipynb\",\n\t\t\t\t\t\"name\": \"Test Session\",\n\t\t\t\t\t\"type\": \"notebook\",\n\t\t\t\t\t\"kernel\": {\n\t\t\t\t\t\t\"id\": \"test-kernel-id\",\n\t\t\t\t\t\t\"name\": \"python3\"\n\t\t\t\t\t}\n\t\t\t\t}`))\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\n\t\t// Handle specific session requests\n\t\tif strings.HasPrefix(r.URL.Path, \"/api/sessions/test-session-id\") {\n\t\t\tif r.Method == http.MethodDelete {\n\t\t\t\t// Delete session\n\t\t\t\tw.WriteHeader(http.StatusNoContent)\n\t\t\t\treturn\n\t\t\t} else if r.Method == http.MethodPatch {\n\t\t\t\t// Modify session\n\t\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\t\tw.Write([]byte(`{\n\t\t\t\t\t\"id\": \"test-session-id\",\n\t\t\t\t\t\"path\": \"/path/to/updated-notebook.ipynb\",\n\t\t\t\t\t\"name\": \"Updated Test Session\",\n\t\t\t\t\t\"type\": \"notebook\",\n\t\t\t\t\t\"kernel\": {\n\t\t\t\t\t\t\"id\": \"test-kernel-id\",\n\t\t\t\t\t\t\"name\": \"python3\"\n\t\t\t\t\t}\n\t\t\t\t}`))\n\t\t\t\treturn\n\t\t\t} else if r.Method == http.MethodGet {\n\t\t\t\t// Get session\n\t\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\t\tw.Write([]byte(`{\n\t\t\t\t\t\"id\": \"test-session-id\",\n\t\t\t\t\t\"path\": \"/path/to/notebook.ipynb\",\n\t\t\t\t\t\"name\": \"Test Session\",\n\t\t\t\t\t\"type\": \"notebook\",\n\t\t\t\t\t\"kernel\": {\n\t\t\t\t\t\t\"id\": \"test-kernel-id\",\n\t\t\t\t\t\t\"name\": \"python3\"\n\t\t\t\t\t}\n\t\t\t\t}`))\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\n\t\t// Handle kernel requests\n\t\tif r.URL.Path == \"/api/kernels\" {\n\t\t\tif r.Method == http.MethodGet {\n\t\t\t\t// List kernels\n\t\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\t\tw.Write([]byte(`[{\n\t\t\t\t\t\"id\": \"test-kernel-id\",\n\t\t\t\t\t\"name\": \"python3\",\n\t\t\t\t\t\"execution_state\": \"idle\"\n\t\t\t\t}]`))\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\n\t\t// Handle specific kernel requests\n\t\tif strings.HasPrefix(r.URL.Path, \"/api/kernels/test-kernel-id\") {\n\t\t\tif r.Method == http.MethodGet {\n\t\t\t\t// Get kernel\n\t\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\t\tw.Write([]byte(`{\n\t\t\t\t\t\"id\": \"test-kernel-id\",\n\t\t\t\t\t\"name\": \"python3\",\n\t\t\t\t\t\"execution_state\": \"idle\"\n\t\t\t\t}`))\n\t\t\t\treturn\n\t\t\t} else if r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, \"/restart\") {\n\t\t\t\t// Restart kernel\n\t\t\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\t\t\tw.Write([]byte(`{\n\t\t\t\t\t\"id\": \"test-kernel-id\",\n\t\t\t\t\t\"name\": \"python3\",\n\t\t\t\t\t\"restarted\": true\n\t\t\t\t}`))\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\n\t\t// If it's a WebSocket connection request, upgrade to WebSocket\n\t\tif strings.HasSuffix(r.URL.Path, \"/channels\") {\n\t\t\t// Return 404, as WebSocket connections will be handled by a dedicated WebSocket server\n\t\t\tw.WriteHeader(http.StatusNotFound)\n\t\t\treturn\n\t\t}\n\n\t\t// For other requests, return 404\n\t\tw.WriteHeader(http.StatusNotFound)\n\t}))\n\tdefer httpServer.Close()\n\n\t// Create mock WebSocket server for code execution\n\twsServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\tif !strings.HasSuffix(r.URL.Path, \"/channels\") {\n\t\t\tw.WriteHeader(http.StatusNotFound)\n\t\t\treturn\n\t\t}\n\n\t\t// Upgrade HTTP connection to WebSocket\n\t\tupgrader := websocket.Upgrader{\n\t\t\tCheckOrigin: func(r *http.Request) bool { return true },\n\t\t}\n\t\tconn, err := upgrader.Upgrade(w, r, nil)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to upgrade connection to WebSocket: %v\", err)\n\t\t}\n\t\tdefer conn.Close()\n\n\t\t// Continuously handle WebSocket messages\n\t\tfor {\n\t\t\t// Read request message\n\t\t\tvar msg execute.Message\n\t\t\terr := conn.ReadJSON(&msg)\n\t\t\tif err != nil {\n\t\t\t\tbreak\n\t\t\t}\n\n\t\t\t// If it's an execute request, send mock response\n\t\t\tif msg.Header.MessageType == string(execute.MsgExecuteRequest) {\n\t\t\t\t// Send stream output\n\t\t\t\tstreamContent, _ := json.Marshal(execute.StreamOutput{\n\t\t\t\t\tName: execute.StreamStdout,\n\t\t\t\t\tText: \"Hello from test WebSocket!\\n\",\n\t\t\t\t})\n\n\t\t\t\tstreamMsg := execute.Message{\n\t\t\t\t\tHeader: execute.Header{\n\t\t\t\t\t\tMessageID: \"stream-msg-id\",\n\t\t\t\t\t\tSession: msg.Header.Session,\n\t\t\t\t\t\tMessageType: string(execute.MsgStream),\n\t\t\t\t\t},\n\t\t\t\t\tParentHeader: msg.Header,\n\t\t\t\t\tContent: json.RawMessage(streamContent),\n\t\t\t\t}\n\t\t\t\tconn.WriteJSON(streamMsg)\n\n\t\t\t\t// Send execution result\n\t\t\t\tresultContent, _ := json.Marshal(execute.ExecuteResult{\n\t\t\t\t\tExecutionCount: 1,\n\t\t\t\t\tData: map[string]interface{}{\n\t\t\t\t\t\t\"text/plain\": \"Integration test result\",\n\t\t\t\t\t},\n\t\t\t\t\tMetadata: map[string]interface{}{},\n\t\t\t\t})\n\n\t\t\t\texecuteResultMsg := execute.Message{\n\t\t\t\t\tHeader: execute.Header{\n\t\t\t\t\t\tMessageID: \"result-msg-id\",\n\t\t\t\t\t\tSession: msg.Header.Session,\n\t\t\t\t\t\tMessageType: string(execute.MsgExecuteResult),\n\t\t\t\t\t},\n\t\t\t\t\tParentHeader: msg.Header,\n\t\t\t\t\tContent: json.RawMessage(resultContent),\n\t\t\t\t}\n\t\t\t\tconn.WriteJSON(executeResultMsg)\n\n\t\t\t\t// Send status message\n\t\t\t\tstatusContent, _ := json.Marshal(execute.StatusUpdate{\n\t\t\t\t\tExecutionState: execute.StateIdle,\n\t\t\t\t})\n\n\t\t\t\tstatusMsg := execute.Message{\n\t\t\t\t\tHeader: execute.Header{\n\t\t\t\t\t\tMessageID: \"status-msg-id\",\n\t\t\t\t\t\tSession: msg.Header.Session,\n\t\t\t\t\t\tMessageType: string(execute.MsgStatus),\n\t\t\t\t\t},\n\t\t\t\t\tParentHeader: msg.Header,\n\t\t\t\t\tContent: json.RawMessage(statusContent),\n\t\t\t\t}\n\t\t\t\tconn.WriteJSON(statusMsg)\n\t\t\t}\n\t\t}\n\t}))\n\tdefer wsServer.Close()\n\n\t// Create Jupyter client\n\tclient := NewClient(httpServer.URL)\n\tclient.SetToken(\"test-token\")\n\n\t// Test 1: Validate authentication\n\tstatus, err := client.ValidateAuth()\n\tif err != nil {\n\t\tt.Fatalf(\"Authentication validation failed: %v\", err)\n\t}\n\tif status != \"ok\" {\n\t\tt.Errorf(\"Authentication status incorrect, expected 'ok', got '%s'\", status)\n\t}\n\n\t// Test 2: Get kernel specs\n\tspecs, err := client.GetKernelSpecs()\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to get kernel specs: %v\", err)\n\t}\n\tif specs.Default != \"python3\" {\n\t\tt.Errorf(\"Default kernel incorrect, expected 'python3', got '%s'\", specs.Default)\n\t}\n\tif len(specs.Kernelspecs) != 1 {\n\t\tt.Errorf(\"Kernel count incorrect, expected 1, got %d\", len(specs.Kernelspecs))\n\t}\n\n\t// Test 3: Create session\n\tsession, err := client.CreateSession(\"Test Session\", \"/path/to/notebook.ipynb\", \"python3\")\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to create session: %v\", err)\n\t}\n\tif session.ID != \"test-session-id\" {\n\t\tt.Errorf(\"Session ID incorrect, expected 'test-session-id', got '%s'\", session.ID)\n\t}\n\tif session.Kernel.ID != \"test-kernel-id\" {\n\t\tt.Errorf(\"Kernel ID incorrect, expected 'test-kernel-id', got '%s'\", session.Kernel.ID)\n\t}\n\n\t// Modify WebSocket URL to point to WebSocket test server\n\twsURL := \"ws\" + strings.TrimPrefix(wsServer.URL, \"http\") + \"/api/kernels/test-kernel-id/channels\"\n\n\t// Test 4: Connect to kernel and execute code\n\texecutor := execute.NewExecutor(wsURL, nil)\n\terr = executor.Connect()\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to connect to kernel: %v\", err)\n\t}\n\tdefer executor.Disconnect()\n\n\t// Execute code\n\terr = executor.ExecuteCodeWithCallback(\"print('Hello from integration test!')\", execute.CallbackHandler{})\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to execute code: %v\", err)\n\t}\n\n\t// Test 5: Delete session\n\terr = client.DeleteSession(session.ID)\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to delete session: %v\", err)\n\t}\n}\n" }, { "path": "components/execd/pkg/jupyter/kernel/kernel.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n// Package kernel provides functionality for managing Jupyter kernels\npackage kernel\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\n// Client is the client for kernel management\ntype Client struct {\n\t// baseURL is the base URL of the Jupyter server\n\tbaseURL string\n\n\t// httpClient is the client for sending HTTP requests, with authentication support\n\thttpClient *http.Client\n}\n\n// NewClient creates a new kernel management client\nfunc NewClient(baseURL string, httpClient *http.Client) *Client {\n\treturn &Client{\n\t\tbaseURL: baseURL,\n\t\thttpClient: httpClient,\n\t}\n}\n\n// GetKernelSpecs retrieves the list of available kernel specifications\nfunc (c *Client) GetKernelSpecs() (*KernelSpecs, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/kernelspecs\", c.baseURL)\n\n\t// Send GET request\n\tresp, err := c.httpClient.Get(url)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar specs KernelSpecs\n\tif err := json.Unmarshal(body, &specs); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn &specs, nil\n}\n\n// ListKernels retrieves the list of all running kernels\nfunc (c *Client) ListKernels() ([]*Kernel, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/kernels\", c.baseURL)\n\n\t// Send GET request\n\tresp, err := c.httpClient.Get(url)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar kernels []*Kernel\n\tif err := json.Unmarshal(body, &kernels); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn kernels, nil\n}\n\n// GetKernel retrieves information about a specific kernel\nfunc (c *Client) GetKernel(kernelId string) (*Kernel, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/kernels/%s\", c.baseURL, kernelId)\n\n\t// Send GET request\n\tresp, err := c.httpClient.Get(url)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar kernel Kernel\n\tif err := json.Unmarshal(body, &kernel); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn &kernel, nil\n}\n\n// StartKernel starts a new kernel\nfunc (c *Client) StartKernel(name string) (*Kernel, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/kernels\", c.baseURL)\n\n\t// Build request body\n\treqBody := &KernelStartRequest{\n\t\tName: name,\n\t}\n\n\t// Serialize request body to JSON\n\tjsonData, err := json.Marshal(reqBody)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to serialize request: %w\", err)\n\t}\n\n\t// Create POST request\n\treq, err := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(jsonData))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create request: %w\", err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t// Send request\n\tresp, err := c.httpClient.Do(req)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar kernel Kernel\n\tif err := json.Unmarshal(body, &kernel); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn &kernel, nil\n}\n\n// RestartKernel restarts the specified kernel\nfunc (c *Client) RestartKernel(kernelId string) (bool, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/kernels/%s/restart\", c.baseURL, kernelId)\n\n\t// Create POST request\n\treq, err := http.NewRequest(http.MethodPost, url, nil)\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"failed to create request: %w\", err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t// Send request\n\tresp, err := c.httpClient.Do(req)\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusOK {\n\t\treturn false, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar response KernelRestartResponse\n\tif err := json.Unmarshal(body, &response); err != nil {\n\t\treturn false, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn response.Restarted, nil\n}\n\n// InterruptKernel interrupts the specified kernel\nfunc (c *Client) InterruptKernel(kernelId string) error {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/kernels/%s/interrupt\", c.baseURL, kernelId)\n\n\t// Create POST request\n\treq, err := http.NewRequest(http.MethodPost, url, nil)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create request: %w\", err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t// Send request\n\tresp, err := c.httpClient.Do(req)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK {\n\t\treturn fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\treturn nil\n}\n\n// ShutdownKernel shuts down the specified kernel\nfunc (c *Client) ShutdownKernel(kernelId string, restart bool) error {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/kernels/%s\", c.baseURL, kernelId)\n\n\t// Build request body\n\treqBody := &KernelShutdownRequest{\n\t\tRestart: restart,\n\t}\n\n\t// Serialize request body to JSON\n\tjsonData, err := json.Marshal(reqBody)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to serialize request: %w\", err)\n\t}\n\n\t// Create DELETE request\n\treq, err := http.NewRequest(http.MethodDelete, url, bytes.NewBuffer(jsonData))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create request: %w\", err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t// Send request\n\tresp, err := c.httpClient.Do(req)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK {\n\t\treturn fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\treturn nil\n}\n" }, { "path": "components/execd/pkg/jupyter/kernel/kernelspecs.json", "content": "{\n \"default\" : \"python3\",\n \"kernelspecs\" : {\n \"python3\" : {\n \"name\" : \"python3\",\n \"spec\" : {\n \"argv\" : [ \"/opt/conda/bin/python\", \"-m\", \"ipykernel_launcher\", \"-f\", \"{connection_file}\" ],\n \"env\" : { },\n \"display_name\" : \"Python 3 (ipykernel)\",\n \"language\" : \"python\",\n \"interrupt_mode\" : \"signal\",\n \"metadata\" : {\n \"debugger\" : true\n }\n },\n \"resources\" : {\n \"logo-svg\" : \"/kernelspecs/python3/logo-svg.svg\",\n \"logo-64x64\" : \"/kernelspecs/python3/logo-64x64.png\",\n \"logo-32x32\" : \"/kernelspecs/python3/logo-32x32.png\"\n }\n }\n }\n}\n" }, { "path": "components/execd/pkg/jupyter/kernel/types.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n// Package kernel provides functionality for managing Jupyter kernels\npackage kernel\n\nimport (\n\t\"time\"\n)\n\n// KernelSpecs contains available kernel specification information\ntype KernelSpecs struct {\n\t// Default is the name of the default kernel\n\tDefault string `json:\"default\"`\n\n\t// Kernelspecs is a mapping from kernel names to kernel specifications\n\tKernelspecs map[string]*KernelSpecInfo `json:\"kernelspecs\"`\n}\n\n// KernelSpecInfo contains detailed kernel specification information\ntype KernelSpecInfo struct {\n\t// Name is the name of the kernel\n\tName string `json:\"name\"`\n\n\tSpec KernelSpecDetail `json:\"spec\"`\n\n\t// Resources contains resource paths related to the kernel\n\tResources map[string]string `json:\"resources,omitempty\"`\n}\n\ntype KernelSpecDetail struct {\n\tArgv []string `json:\"argv,omitempty\"`\n\n\t// DisplayName is the display name of the kernel\n\tDisplayName string `json:\"display_name\"`\n\n\t// Language is the programming language used by the kernel\n\tLanguage string `json:\"language,omitempty\"`\n\n\t// InterruptMode is the interrupt mode of the kernel\n\tInterruptMode string `json:\"interrupt_mode,omitempty\"`\n}\n\n// Kernel represents a running kernel instance\ntype Kernel struct {\n\t// ID is the unique identifier of the kernel\n\tID string `json:\"id\"`\n\n\t// Name is the name of the kernel\n\tName string `json:\"name\"`\n\n\t// LastActivity is the timestamp of the kernel's last activity\n\tLastActivity time.Time `json:\"last_activity,omitempty\"`\n\n\t// Connections is the number of clients currently connected to the kernel\n\tConnections int `json:\"connections,omitempty\"`\n\n\t// ExecutionState is the execution state of the kernel (e.g., idle, busy)\n\tExecutionState string `json:\"execution_state,omitempty\"`\n}\n\n// KernelStartRequest is the request for starting a new kernel\ntype KernelStartRequest struct {\n\t// Name is the name of the kernel to start\n\tName string `json:\"name\"`\n\n\t// Path is the optional path for the kernel\n\tPath string `json:\"path,omitempty\"`\n}\n\n// KernelRestartResponse representsresponse of kernel restart\ntype KernelRestartResponse struct {\n\t// ID is the ID of the restarted kernel\n\tID string `json:\"id\"`\n\n\t// Name is the restarted kernel name\n\tName string `json:\"name\"`\n\n\t// Restarted represents whether the kernel was successfully restarted\n\tRestarted bool `json:\"restarted\"`\n\n\t// LastActivity is the timestamp of the kernel's last activity\n\tLastActivity time.Time `json:\"last_activity,omitempty\"`\n}\n\n// KernelInterruptRequest request to interrupt a kernel\ntype KernelInterruptRequest struct {\n\t// Restart represents whether to restart the kernel after interruption\n\tRestart bool `json:\"restart,omitempty\"`\n}\n\n// KernelShutdownRequest request to close a kernel\ntype KernelShutdownRequest struct {\n\t// Restart representswhether torestart kernel after shutdown\n\tRestart bool `json:\"restart\"`\n}\n\n// KernelStatus represents the status of the kernel\ntype KernelStatus string\n\nconst (\n\t// KernelStatusIdle representskernel is idle\n\tKernelStatusIdle KernelStatus = \"idle\"\n\n\t// KernelStatusBusy representskernel is busy\n\tKernelStatusBusy KernelStatus = \"busy\"\n\n\t// KernelStatusStarting representskernel is starting\n\tKernelStatusStarting KernelStatus = \"starting\"\n\n\t// KernelStatusRestarting represents the kernel is restarting\n\tKernelStatusRestarting KernelStatus = \"restarting\"\n\n\t// KernelStatusDead represents the kernel is dead\n\tKernelStatusDead KernelStatus = \"dead\"\n)\n" }, { "path": "components/execd/pkg/jupyter/live_integration_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage jupyter\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n)\n\n// authTransport is a custom transport layer for adding authentication headers\ntype authTransport struct {\n\ttoken string\n\tbase http.RoundTripper\n}\n\n// RoundTrip implements the http.RoundTripper interface, adding authentication headers to each request\nfunc (t *authTransport) RoundTrip(req *http.Request) (*http.Response, error) {\n\t// Clone the request to avoid modifying the original request\n\treqClone := req.Clone(req.Context())\n\t// Add authentication header\n\treqClone.Header.Set(\"Authorization\", \"Token \"+t.token)\n\t// Send the request using the base transport layer\n\treturn t.base.RoundTrip(reqClone)\n}\n\n// TestLiveServerIntegration tests SDK integration with a real Jupyter server\nfunc TestLiveServerIntegration(t *testing.T) {\n\tt.Skip()\n\t// Get configuration from environment variables, use default values if not set\n\tjupyterURL := getEnv(\"JUPYTER_URL\", \"\")\n\tjupyterToken := getEnv(\"JUPYTER_TOKEN\", \"\")\n\tif jupyterURL == \"\" || jupyterToken == \"\" {\n\t\tt.Skip(\"JUPYTER_URL and JUPYTER_TOKEN environment variables must be set to run this test\")\n\t}\n\n\t// Output test information\n\tt.Logf(\"Connecting to Jupyter server: %s\", jupyterURL)\n\n\t// Create HTTP client with authentication capability\n\thttpClient := &http.Client{\n\t\tTransport: &authTransport{\n\t\t\ttoken: jupyterToken,\n\t\t\tbase: http.DefaultTransport,\n\t\t},\n\t}\n\n\t// Create client and set authentication\n\tclient := NewClient(jupyterURL,\n\t\tWithToken(jupyterToken), // Keep Token setting to support ValidateAuth and WebSocket connections\n\t\tWithHTTPClient(httpClient))\n\n\t// Test 1: Validate authentication\n\tt.Run(\"Validate Authentication\", func(t *testing.T) {\n\t\tstatus, err := client.ValidateAuth()\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Authentication validation failed: %v\", err)\n\t\t}\n\t\tif status != \"ok\" {\n\t\t\tt.Errorf(\"Authentication status incorrect, expected 'ok', got '%s'\", status)\n\t\t}\n\t\tt.Logf(\"Authentication validation successful! Status: %s\", status)\n\t})\n\n\t// Test 2: Get kernel specs\n\tvar kernelName string\n\tt.Run(\"Get Kernel Specs\", func(t *testing.T) {\n\t\tspecs, err := client.GetKernelSpecs()\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to get kernel specs: %v\", err)\n\t\t}\n\t\tif specs.Default == \"\" {\n\t\t\tt.Errorf(\"No default kernel\")\n\t\t}\n\t\tif len(specs.Kernelspecs) == 0 {\n\t\t\tt.Errorf(\"No available kernels\")\n\t\t}\n\n\t\t// Use default kernel or Python kernel (if available)\n\t\tkernelName = specs.Default\n\t\tfor name, spec := range specs.Kernelspecs {\n\t\t\tif spec.Spec.Language == \"python\" {\n\t\t\t\tkernelName = name\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\n\t\tt.Logf(\"Get kernel specs successful! Default kernel: %s, Selected kernel: %s\", specs.Default, kernelName)\n\t\tt.Logf(\"Available kernels: %v\", specs.Kernelspecs)\n\t})\n\n\t// Test 3: List sessions\n\tt.Run(\"List Sessions\", func(t *testing.T) {\n\t\tsessions, err := client.ListSessions()\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to list sessions: %v\", err)\n\t\t}\n\t\tt.Logf(\"List sessions successful! Number of existing sessions: %d\", len(sessions))\n\t\tfor i, s := range sessions {\n\t\t\tt.Logf(\"Session %d: ID=%s, Path=%s, Kernel=%s\", i+1, s.ID, s.Path, s.Kernel.Name)\n\t\t}\n\t})\n\n\t// Test 4: Create new session\n\tvar sessionID string\n\tt.Run(\"Create Session\", func(t *testing.T) {\n\t\t// Generate unique name for test session\n\t\tsessionName := fmt.Sprintf(\"test-session-%d\", time.Now().Unix())\n\t\tsessionPath := \"/test-notebook.ipynb\"\n\n\t\tsession, err := client.CreateSession(sessionName, sessionPath, kernelName)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to create session: %v\", err)\n\t\t}\n\t\tif session.ID == \"\" {\n\t\t\tt.Errorf(\"Created session has no ID\")\n\t\t}\n\t\tif session.Kernel.ID == \"\" {\n\t\t\tt.Errorf(\"Created session has no kernel ID\")\n\t\t}\n\n\t\t// Save session ID for subsequent tests\n\t\tsessionID = session.ID\n\n\t\tt.Logf(\"Create session successful! Session ID: %s, Kernel ID: %s\", session.ID, session.Kernel.ID)\n\t})\n\n\t// Test 5: Get created session\n\tvar kernelID string\n\tt.Run(\"Get Session\", func(t *testing.T) {\n\t\tif sessionID == \"\" {\n\t\t\tt.Skip(\"No session ID, skipping test\")\n\t\t}\n\n\t\tsession, err := client.GetSession(sessionID)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to get session: %v\", err)\n\t\t}\n\t\tif session.ID != sessionID {\n\t\t\tt.Errorf(\"Session ID mismatch, expected '%s', got '%s'\", sessionID, session.ID)\n\t\t}\n\n\t\t// Save kernel ID for subsequent tests\n\t\tkernelID = session.Kernel.ID\n\n\t\tt.Logf(\"Get session successful! Session name: %s, Kernel name: %s\", session.Name, session.Kernel.Name)\n\t})\n\n\t// Test 6: List all kernels\n\tt.Run(\"List Kernels\", func(t *testing.T) {\n\t\tkernels, err := client.ListKernels()\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to list kernels: %v\", err)\n\t\t}\n\t\tt.Logf(\"List kernels successful! Number of kernels: %d\", len(kernels))\n\t\tfor i, k := range kernels {\n\t\t\tt.Logf(\"Kernel %d: ID=%s, Name=%s, State=%s\", i+1, k.ID, k.Name, k.ExecutionState)\n\t\t}\n\n\t\t// Verify that the created kernel is in the list\n\t\tif kernelID != \"\" {\n\t\t\tfound := false\n\t\t\tfor _, k := range kernels {\n\t\t\t\tif k.ID == kernelID {\n\t\t\t\t\tfound = true\n\t\t\t\t\tbreak\n\t\t\t\t}\n\t\t\t}\n\t\t\tif !found {\n\t\t\t\tt.Errorf(\"Cannot find created kernel in kernel list ID=%s\", kernelID)\n\t\t\t}\n\t\t}\n\t})\n\n\t// Test 7: Connect to kernel and execute code\n\tt.Run(\"Execute Code\", func(t *testing.T) {\n\t\tif kernelID == \"\" {\n\t\t\tt.Skip(\"No kernel ID, skipping test\")\n\t\t}\n\n\t\t// Connect to kernel\n\t\terr := client.ConnectToKernel(kernelID)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to connect to kernel: %v\", err)\n\t\t}\n\t\tdefer client.DisconnectFromKernel(kernelID)\n\n\t\t// Execute simple code\n\t\tcode := \"print('Hello, Jupyter!')\\nresult = 2 + 2\\nresult\"\n\t\tt.Logf(\"Executing code:\\n%s\", code)\n\n\t\terr = client.ExecuteCodeWithCallback(code, execute.CallbackHandler{})\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to execute code: %v\", err)\n\t\t}\n\t})\n\n\t// Test 7: Connect to kernel and execute code\n\tt.Run(\"Execute Code\", func(t *testing.T) {\n\t\tif kernelID == \"\" {\n\t\t\tt.Skip(\"No kernel ID, skipping test\")\n\t\t}\n\n\t\t// Connect to kernel\n\t\terr := client.ConnectToKernel(kernelID)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to connect to kernel: %v\", err)\n\t\t}\n\t\tdefer client.DisconnectFromKernel(kernelID)\n\n\t\t// Execute simple code\n\t\tcode := \"print(f'2 + 2 = {result}')\\nresult\"\n\t\tt.Logf(\"Executing code:\\n%s\", code)\n\n\t\terr = client.ExecuteCodeWithCallback(code, execute.CallbackHandler{})\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to execute code: %v\", err)\n\t\t}\n\t})\n\n\t// Test 8: Execute complex code with different types of output\n\tt.Run(\"Execute Complex Code\", func(t *testing.T) {\n\t\tif kernelID == \"\" {\n\t\t\tt.Skip(\"No kernel ID, skipping test\")\n\t\t}\n\n\t\t// Connect to kernel\n\t\terr := client.ConnectToKernel(kernelID)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to connect to kernel: %v\", err)\n\t\t}\n\t\tdefer client.DisconnectFromKernel(kernelID)\n\n\t\t// Execute code that generates multiple output types\n\t\tcode := `\n# Display table data\nimport pandas as pd\nimport numpy as np\ntry:\n df = pd.DataFrame({\n 'A': np.random.rand(5),\n 'B': np.random.rand(5)\n })\n display(df)\n print(\"DataFrame created successfully\")\nexcept Exception as e:\n print(f\"Error creating DataFrame: {e}\")\n\n# Generate error\ntry:\n print(undefined_variable)\nexcept Exception as e:\n print(f\"Expected error: {e}\")\n\n# Return dictionary\n{'hello': 'world', 'number': 42}\n`\n\n\t\tt.Logf(\"Executing complex code...\")\n\n\t\terr = client.ExecuteCodeWithCallback(code, execute.CallbackHandler{})\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to execute complex code: %v\", err)\n\t\t}\n\t})\n\n\t// Test 9: Restart kernel\n\tt.Run(\"Restart Kernel\", func(t *testing.T) {\n\t\tif kernelID == \"\" {\n\t\t\tt.Skip(\"No kernel ID, skipping test\")\n\t\t}\n\n\t\t// Restart kernel\n\t\trestarted, err := client.RestartKernel(kernelID)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to restart kernel: %v\", err)\n\t\t}\n\n\t\t// Wait for kernel restart to complete\n\t\ttime.Sleep(2 * time.Second)\n\n\t\t// Verify kernel state\n\t\tkernel, err := client.GetKernel(kernelID)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to get kernel: %v\", err)\n\t\t}\n\n\t\tt.Logf(\"Restart kernel successful! Restart status: %v, Kernel state: %s\", restarted, kernel.ExecutionState)\n\t})\n\n\t// Test 10: Close session\n\tt.Run(\"Close Session\", func(t *testing.T) {\n\t\tif sessionID == \"\" {\n\t\t\tt.Skip(\"No session ID, skipping test\")\n\t\t}\n\n\t\t// Delete session\n\t\terr := client.DeleteSession(sessionID)\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to delete session: %v\", err)\n\t\t}\n\n\t\t// Verify session is deleted\n\t\tsessions, err := client.ListSessions()\n\t\tif err != nil {\n\t\t\tt.Fatalf(\"Failed to list sessions: %v\", err)\n\t\t}\n\n\t\tfor _, s := range sessions {\n\t\t\tif s.ID == sessionID {\n\t\t\t\tt.Errorf(\"Session still exists, not properly deleted ID=%s\", sessionID)\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\n\t\tt.Logf(\"Close session successful!\")\n\t})\n}\n\n// Helper function: Get environment variable, use default value if not exists\nfunc getEnv(key, defaultValue string) string {\n\tvalue := os.Getenv(key)\n\tif value == \"\" {\n\t\treturn defaultValue\n\t}\n\treturn value\n}\n\n// Helper function: Truncate string\nfunc truncateString(s string, maxLen int) string {\n\tif len(s) <= maxLen {\n\t\treturn s\n\t}\n\treturn s[:maxLen] + \"...\"\n}\n\n// Helper function: Get all keys from map\nfunc getKeys(m map[string]interface{}) []string {\n\tkeys := make([]string, 0, len(m))\n\tfor k := range m {\n\t\tkeys = append(keys, k)\n\t}\n\treturn keys\n}\n" }, { "path": "components/execd/pkg/jupyter/session/session.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n// Package session provides functionality for managing Jupyter sessions\npackage session\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\n// Client is the client for session management\ntype Client struct {\n\t// baseURL is the base URL of the Jupyter server\n\tbaseURL string\n\n\t// httpClient is the client for sending HTTP requests, with authentication support\n\thttpClient *http.Client\n}\n\n// NewClient creates a new session management client\nfunc NewClient(baseURL string, httpClient *http.Client) *Client {\n\treturn &Client{\n\t\tbaseURL: baseURL,\n\t\thttpClient: httpClient,\n\t}\n}\n\n// ListSessions retrieves the list of all active sessions\nfunc (c *Client) ListSessions() ([]*Session, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/sessions\", c.baseURL)\n\n\t// Send GET request\n\tresp, err := c.httpClient.Get(url)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar sessions []*Session\n\tif err := json.Unmarshal(body, &sessions); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn sessions, nil\n}\n\n// GetSession retrieves information about a specific session\nfunc (c *Client) GetSession(sessionId string) (*Session, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/sessions/%s\", c.baseURL, sessionId)\n\n\t// Send GET request\n\tresp, err := c.httpClient.Get(url)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar session Session\n\tif err := json.Unmarshal(body, &session); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn &session, nil\n}\n\n// CreateSession creates a new session\nfunc (c *Client) CreateSession(name, ipynb, kernel string) (*Session, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/sessions\", c.baseURL)\n\n\t// Build request body\n\treqBody := &SessionCreateRequest{\n\t\tPath: ipynb,\n\t\tName: name,\n\t\tType: DefaultSessionType,\n\t\tKernel: &KernelSpec{\n\t\t\tName: kernel,\n\t\t},\n\t}\n\n\t// Serialize request body to JSON\n\tjsonData, err := json.Marshal(reqBody)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to serialize request: %w\", err)\n\t}\n\n\t// Create POST request\n\treq, err := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(jsonData))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create request: %w\", err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t// Send request\n\tresp, err := c.httpClient.Do(req)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar session Session\n\tif err := json.Unmarshal(body, &session); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn &session, nil\n}\n\n// ModifySession modifies properties of an existing session\nfunc (c *Client) ModifySession(sessionId, name, path, kernel string) (*Session, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/sessions/%s\", c.baseURL, sessionId)\n\n\t// Build request body\n\treqBody := &SessionUpdateRequest{}\n\tif name != \"\" {\n\t\treqBody.Name = name\n\t}\n\tif path != \"\" {\n\t\treqBody.Path = path\n\t}\n\tif kernel != \"\" {\n\t\treqBody.Kernel = &KernelSpec{\n\t\t\tName: kernel,\n\t\t}\n\t}\n\n\t// Serialize request body to JSON\n\tjsonData, err := json.Marshal(reqBody)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to serialize request: %w\", err)\n\t}\n\n\t// Create PATCH request\n\treq, err := http.NewRequest(http.MethodPatch, url, bytes.NewBuffer(jsonData))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create request: %w\", err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t// Send request\n\tresp, err := c.httpClient.Do(req)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar session Session\n\tif err := json.Unmarshal(body, &session); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn &session, nil\n}\n\n// DeleteSession deletes the specified session\nfunc (c *Client) DeleteSession(sessionId string) error {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/sessions/%s\", c.baseURL, sessionId)\n\n\t// Create DELETE request\n\treq, err := http.NewRequest(http.MethodDelete, url, nil)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create request: %w\", err)\n\t}\n\n\t// Send request\n\tresp, err := c.httpClient.Do(req)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK {\n\t\treturn fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\treturn nil\n}\n\n// CreateSessionWithOptions usingoption to create a new session\nfunc (c *Client) CreateSessionWithOptions(options *SessionOptions) (*Session, error) {\n\t// Build request URL\n\turl := fmt.Sprintf(\"%s/api/sessions\", c.baseURL)\n\n\t// Build request body\n\treqBody := &SessionCreateRequest{\n\t\tPath: options.Path,\n\t\tName: options.Name,\n\t}\n\n\t// set session type\n\tif options.Type != \"\" {\n\t\treqBody.Type = options.Type\n\t} else {\n\t\treqBody.Type = DefaultSessionType\n\t}\n\n\t// set kernel information\n\tif options.KernelID != \"\" {\n\t\t// If kernel ID is provided, use existing kernel\n\t\treqBody.Kernel = &KernelSpec{\n\t\t\tID: options.KernelID,\n\t\t}\n\t} else if options.KernelName != \"\" {\n\t\t// If kernel name is provided, start new kernel\n\t\treqBody.Kernel = &KernelSpec{\n\t\t\tName: options.KernelName,\n\t\t}\n\t}\n\n\t// Serialize request body to JSON\n\tjsonData, err := json.Marshal(reqBody)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to serialize request: %w\", err)\n\t}\n\n\t// Create POST request\n\treq, err := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(jsonData))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create request: %w\", err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t// Send request\n\tresp, err := c.httpClient.Do(req)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to send request: %w\", err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Check response status\n\tif resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {\n\t\treturn nil, fmt.Errorf(\"server returned error status code: %d\", resp.StatusCode)\n\t}\n\n\t// Read response\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read response: %w\", err)\n\t}\n\n\t// Parse JSON response\n\tvar session Session\n\tif err := json.Unmarshal(body, &session); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse response: %w\", err)\n\t}\n\n\treturn &session, nil\n}\n" }, { "path": "components/execd/pkg/jupyter/session/session_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage session\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"testing\"\n)\n\n// Test listing sessions\nfunc TestListSessions(t *testing.T) {\n\t// Create mock server\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\t// Verify request method and path\n\t\tif r.Method != http.MethodGet {\n\t\t\tt.Errorf(\"expected request method GET, got %s\", r.Method)\n\t\t}\n\t\tif r.URL.Path != \"/api/sessions\" {\n\t\t\tt.Errorf(\"expected request path /api/sessions, got %s\", r.URL.Path)\n\t\t}\n\n\t\t// Return mocked session list\n\t\tresponse := `[\n\t\t\t{\n\t\t\t\t\"id\": \"session-1\",\n\t\t\t\t\"path\": \"/path/to/notebook1.ipynb\",\n\t\t\t\t\"name\": \"Session 1\",\n\t\t\t\t\"type\": \"notebook\",\n\t\t\t\t\"kernel\": {\n\t\t\t\t\t\"id\": \"kernel-1\",\n\t\t\t\t\t\"name\": \"python3\",\n\t\t\t\t\t\"last_activity\": \"2023-01-01T00:00:00Z\",\n\t\t\t\t\t\"execution_state\": \"idle\",\n\t\t\t\t\t\"connections\": 1\n\t\t\t\t}\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"id\": \"session-2\",\n\t\t\t\t\"path\": \"/path/to/notebook2.ipynb\",\n\t\t\t\t\"name\": \"Session 2\",\n\t\t\t\t\"type\": \"notebook\",\n\t\t\t\t\"kernel\": {\n\t\t\t\t\t\"id\": \"kernel-2\",\n\t\t\t\t\t\"name\": \"python3\",\n\t\t\t\t\t\"last_activity\": \"2023-01-01T00:00:00Z\",\n\t\t\t\t\t\"execution_state\": \"idle\",\n\t\t\t\t\t\"connections\": 1\n\t\t\t\t}\n\t\t\t}\n\t\t]`\n\n\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\tw.WriteHeader(http.StatusOK)\n\t\tw.Write([]byte(response))\n\t}))\n\tdefer server.Close()\n\n\t// Create client\n\tclient := NewClient(server.URL, &http.Client{})\n\n\t// Fetch session list\n\tsessions, err := client.ListSessions()\n\tif err != nil {\n\t\tt.Fatalf(\"failed to list sessions: %v\", err)\n\t}\n\n\t// Validate session count\n\tif len(sessions) != 2 {\n\t\tt.Errorf(\"expected 2 sessions, got %d\", len(sessions))\n\t}\n\n\t// Validate first session fields\n\tif sessions[0].ID != \"session-1\" {\n\t\tt.Errorf(\"expected session ID 'session-1', got '%s'\", sessions[0].ID)\n\t}\n\tif sessions[0].Name != \"Session 1\" {\n\t\tt.Errorf(\"expected session name 'Session 1', got '%s'\", sessions[0].Name)\n\t}\n\tif sessions[0].Path != \"/path/to/notebook1.ipynb\" {\n\t\tt.Errorf(\"expected session path '/path/to/notebook1.ipynb', got '%s'\", sessions[0].Path)\n\t}\n\tif sessions[0].Type != \"notebook\" {\n\t\tt.Errorf(\"expected session type 'notebook', got '%s'\", sessions[0].Type)\n\t}\n\n\t// Validate first session kernel fields\n\tif sessions[0].Kernel.ID != \"kernel-1\" {\n\t\tt.Errorf(\"expected kernel ID 'kernel-1', got '%s'\", sessions[0].Kernel.ID)\n\t}\n\tif sessions[0].Kernel.Name != \"python3\" {\n\t\tt.Errorf(\"expected kernel name 'python3', got '%s'\", sessions[0].Kernel.Name)\n\t}\n}\n\n// Test creating session\nfunc TestCreateSession(t *testing.T) {\n\t// Create mock server\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\t// Verify request method and path\n\t\tif r.Method != http.MethodPost {\n\t\t\tt.Errorf(\"expected request method POST, got %s\", r.Method)\n\t\t}\n\t\tif r.URL.Path != \"/api/sessions\" {\n\t\t\tt.Errorf(\"expected request path /api/sessions, got %s\", r.URL.Path)\n\t\t}\n\n\t\t// Parse request body\n\t\tvar requestBody SessionCreateRequest\n\t\tdecoder := json.NewDecoder(r.Body)\n\t\tif err := decoder.Decode(&requestBody); err != nil {\n\t\t\tt.Fatalf(\"failed to decode request body: %v\", err)\n\t\t}\n\n\t\t// Validate request params\n\t\tif requestBody.Name != \"Test Session\" {\n\t\t\tt.Errorf(\"expected session name 'Test Session', got '%s'\", requestBody.Name)\n\t\t}\n\t\tif requestBody.Path != \"/path/to/notebook.ipynb\" {\n\t\t\tt.Errorf(\"expected session path '/path/to/notebook.ipynb', got '%s'\", requestBody.Path)\n\t\t}\n\t\tif requestBody.Type != \"notebook\" {\n\t\t\tt.Errorf(\"expected session type 'notebook', got '%s'\", requestBody.Type)\n\t\t}\n\t\tif requestBody.Kernel.Name != \"python3\" {\n\t\t\tt.Errorf(\"expected kernel name 'python3', got '%s'\", requestBody.Kernel.Name)\n\t\t}\n\n\t\t// Return mocked create response\n\t\tresponse := `{\n\t\t\t\"id\": \"new-session-id\",\n\t\t\t\"path\": \"/path/to/notebook.ipynb\",\n\t\t\t\"name\": \"Test Session\",\n\t\t\t\"type\": \"notebook\",\n\t\t\t\"kernel\": {\n\t\t\t\t\"id\": \"new-kernel-id\",\n\t\t\t\t\"name\": \"python3\",\n\t\t\t\t\"last_activity\": \"2023-01-01T00:00:00Z\",\n\t\t\t\t\"execution_state\": \"idle\",\n\t\t\t\t\"connections\": 0\n\t\t\t}\n\t\t}`\n\n\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\tw.WriteHeader(http.StatusCreated)\n\t\tw.Write([]byte(response))\n\t}))\n\tdefer server.Close()\n\n\t// Create client\n\tclient := NewClient(server.URL, &http.Client{})\n\n\t// Create session\n\tnewSession, err := client.CreateSession(\"Test Session\", \"/path/to/notebook.ipynb\", \"python3\")\n\tif err != nil {\n\t\tt.Fatalf(\"failed to create session: %v\", err)\n\t}\n\n\t// Validate created session\n\tif newSession.ID != \"new-session-id\" {\n\t\tt.Errorf(\"expected session ID 'new-session-id', got '%s'\", newSession.ID)\n\t}\n\tif newSession.Name != \"Test Session\" {\n\t\tt.Errorf(\"expected session name 'Test Session', got '%s'\", newSession.Name)\n\t}\n\tif newSession.Path != \"/path/to/notebook.ipynb\" {\n\t\tt.Errorf(\"expected session path '/path/to/notebook.ipynb', got '%s'\", newSession.Path)\n\t}\n\tif newSession.Kernel.ID != \"new-kernel-id\" {\n\t\tt.Errorf(\"expected kernel ID 'new-kernel-id', got '%s'\", newSession.Kernel.ID)\n\t}\n}\n\n// Test fetching a specific session\nfunc TestGetSession(t *testing.T) {\n\tsessionID := \"test-session-id\"\n\n\t// Create mock server\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\t// Verify request method and path\n\t\tif r.Method != http.MethodGet {\n\t\t\tt.Errorf(\"expected request method GET, got %s\", r.Method)\n\t\t}\n\n\t\texpectedPath := \"/api/sessions/\" + sessionID\n\t\tif r.URL.Path != expectedPath {\n\t\t\tt.Errorf(\"expected request path '%s', got '%s'\", expectedPath, r.URL.Path)\n\t\t}\n\n\t\t// Return mocked session\n\t\tresponse := `{\n\t\t\t\"id\": \"test-session-id\",\n\t\t\t\"path\": \"/path/to/notebook.ipynb\",\n\t\t\t\"name\": \"Test Session\",\n\t\t\t\"type\": \"notebook\",\n\t\t\t\"kernel\": {\n\t\t\t\t\"id\": \"test-kernel-id\",\n\t\t\t\t\"name\": \"python3\",\n\t\t\t\t\"last_activity\": \"2023-01-01T00:00:00Z\",\n\t\t\t\t\"execution_state\": \"idle\",\n\t\t\t\t\"connections\": 1\n\t\t\t}\n\t\t}`\n\n\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\tw.WriteHeader(http.StatusOK)\n\t\tw.Write([]byte(response))\n\t}))\n\tdefer server.Close()\n\n\t// Create client\n\tclient := NewClient(server.URL, &http.Client{})\n\n\t// Fetch session\n\tsession, err := client.GetSession(sessionID)\n\tif err != nil {\n\t\tt.Fatalf(\"failed to get session: %v\", err)\n\t}\n\n\t// Validate session\n\tif session.ID != sessionID {\n\t\tt.Errorf(\"expected session ID '%s', got '%s'\", sessionID, session.ID)\n\t}\n\tif session.Name != \"Test Session\" {\n\t\tt.Errorf(\"expected session name 'Test Session', got '%s'\", session.Name)\n\t}\n\tif session.Kernel.ID != \"test-kernel-id\" {\n\t\tt.Errorf(\"expected kernel ID 'test-kernel-id', got '%s'\", session.Kernel.ID)\n\t}\n}\n" }, { "path": "components/execd/pkg/jupyter/session/sessions.json", "content": "[ {\n \"id\" : \"cb1baca9-a60e-4937-a1d0-18bc1fc45e60\",\n \"path\" : \"my_notebook.ipynb\",\n \"name\" : \"my_session\",\n \"type\" : \"notebook\",\n \"kernel\" : {\n \"id\" : \"d7052326-5c98-4575-bb18-a7902ef5f623\",\n \"name\" : \"python3\",\n \"last_activity\" : \"2025-06-05T09:09:54.420827Z\",\n \"execution_state\" : \"idle\",\n \"connections\" : 0\n },\n \"notebook\" : {\n \"path\" : \"my_notebook.ipynb\",\n \"name\" : \"my_session\"\n }\n}, {\n \"id\" : \"a3378ca1-ba62-4341-9db5-3bc612fb3517\",\n \"path\" : \"Untitled.ipynb\",\n \"name\" : \"Untitled.ipynb\",\n \"type\" : \"notebook\",\n \"kernel\" : {\n \"id\" : \"d7052326-5c98-4575-bb18-a7902ef5f623\",\n \"name\" : \"python3\",\n \"last_activity\" : \"2025-06-05T09:09:54.420827Z\",\n \"execution_state\" : \"idle\",\n \"connections\" : 0\n },\n \"notebook\" : {\n \"path\" : \"Untitled.ipynb\",\n \"name\" : \"Untitled.ipynb\"\n }\n}, {\n \"id\" : \"c4829f29-8430-4dce-b1f5-9d2ac6c4f570\",\n \"path\" : \"/tmp/example_notebook.ipynb\",\n \"name\" : \"example_session\",\n \"type\" : \"notebook\",\n \"kernel\" : {\n \"id\" : \"00349e07-3877-4eb0-a676-0df5b886d770\",\n \"name\" : \"python3\",\n \"last_activity\" : \"2025-06-05T11:51:22.194821Z\",\n \"execution_state\" : \"starting\",\n \"connections\" : 0\n },\n \"notebook\" : {\n \"path\" : \"/tmp/example_notebook.ipynb\",\n \"name\" : \"example_session\"\n }\n}, {\n \"id\" : \"9a8e1857-b737-41a6-8f81-6039f6ae0ac1\",\n \"path\" : \"e0ebd37c-578a-443c-8f58-236984aea7ff\",\n \"name\" : \"session_5c4e8183-9e8a-4879-93b2-5622518193d7\",\n \"type\" : \"notebook\",\n \"kernel\" : {\n \"id\" : \"e8792c3e-3190-4b11-92e8-b7ec9ef44da9\",\n \"name\" : \"python3\",\n \"last_activity\" : \"2025-06-05T12:26:01.610210Z\",\n \"execution_state\" : \"starting\",\n \"connections\" : 0\n },\n \"notebook\" : {\n \"path\" : \"e0ebd37c-578a-443c-8f58-236984aea7ff\",\n \"name\" : \"session_5c4e8183-9e8a-4879-93b2-5622518193d7\"\n }\n}, {\n \"id\" : \"cc06c06d-4f6b-45a5-a546-11a5b5f246f8\",\n \"path\" : \"notebook.ipynb\",\n \"name\" : null,\n \"type\" : \"notebook\",\n \"kernel\" : {\n \"id\" : \"62e7fd9e-ea50-4045-861b-3a5a7073ee22\",\n \"name\" : \"python3\",\n \"last_activity\" : \"2025-06-05T12:26:51.714871Z\",\n \"execution_state\" : \"starting\",\n \"connections\" : 0\n },\n \"notebook\" : {\n \"path\" : \"notebook.ipynb\",\n \"name\" : null\n }\n}, {\n \"id\" : \"db123df4-ec13-4fe0-b3c3-ef85464b8a42\",\n \"path\" : \"/tmp/test.ipynb\",\n \"name\" : \"\",\n \"type\" : \"notebook\",\n \"kernel\" : {\n \"id\" : \"7d3091af-8b0a-474a-be04-f64191a43d0f\",\n \"name\" : \"python3\",\n \"last_activity\" : \"2025-06-06T01:29:16.712732Z\",\n \"execution_state\" : \"starting\",\n \"connections\" : 0\n },\n \"notebook\" : {\n \"path\" : \"/tmp/test.ipynb\",\n \"name\" : \"\"\n }\n} ]\n" }, { "path": "components/execd/pkg/jupyter/session/types.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n// Package session provides functionality for managing Jupyter sessions\npackage session\n\nimport (\n\t\"time\"\n)\n\n// Session represents a Jupyter session\ntype Session struct {\n\t// ID is the unique identifier of the session\n\tID string `json:\"id\"`\n\n\t// Path is the path associated with the session (typically the notebook file path)\n\tPath string `json:\"path\"`\n\n\t// Name is the name of the session\n\tName string `json:\"name\"`\n\n\t// Type is the type of the session (e.g., notebook, console)\n\tType string `json:\"type\"`\n\n\t// Kernel contains information about the kernel associated with the session\n\tKernel *KernelInfo `json:\"kernel\"`\n\n\t// CreatedAt is the timestamp when the session was created\n\tCreatedAt time.Time `json:\"created,omitempty\"`\n\n\t// LastModified is the timestamp when the session was last modified\n\tLastModified time.Time `json:\"last_modified,omitempty\"`\n}\n\n// KernelInfo contains basic kernel information\ntype KernelInfo struct {\n\t// ID is the unique identifier of the kernel\n\tID string `json:\"id\"`\n\n\t// Name is the name of the kernel (e.g., python3, ir)\n\tName string `json:\"name\"`\n\n\t// LastActivity is the timestamp of the kernel's last activity\n\tLastActivity time.Time `json:\"last_activity,omitempty\"`\n\n\t// Connections is the number of clients currently connected to the kernel\n\tConnections int `json:\"connections,omitempty\"`\n\n\t// ExecutionState is the execution state of the kernel (e.g., idle, busy)\n\tExecutionState string `json:\"execution_state,omitempty\"`\n}\n\n// SessionCreateRequest is the request for creating a new session\ntype SessionCreateRequest struct {\n\t// Path is the path associated with the session (typically the notebook file path)\n\tPath string `json:\"path\"`\n\n\t// Name is the name of the session\n\tName string `json:\"name,omitempty\"`\n\n\t// Type is the type of the session (defaults to \"notebook\")\n\tType string `json:\"type,omitempty\"`\n\n\t// Kernel contains information about the kernel to start\n\tKernel *KernelSpec `json:\"kernel,omitempty\"`\n}\n\n// KernelSpec contains kernel specification information\ntype KernelSpec struct {\n\t// Name is the name of the kernel (e.g., python3, ir)\n\tName string `json:\"name\"`\n\n\t// ID is the unique identifier of the kernel (optional, used only when reusing existing kernel)\n\tID string `json:\"id,omitempty\"`\n}\n\n// SessionUpdateRequest request to update an existing session\ntype SessionUpdateRequest struct {\n\t// Path is the new session path\n\tPath string `json:\"path,omitempty\"`\n\n\t// Name is the new session name\n\tName string `json:\"name,omitempty\"`\n\n\t// Type is the new session type\n\tType string `json:\"type,omitempty\"`\n\n\t// Kernel contains the new kernel information\n\tKernel *KernelSpec `json:\"kernel,omitempty\"`\n}\n\n// SessionListResponse represents the response for listing sessions\ntype SessionListResponse []*Session\n\n// SessionOptions contains options for creating or updating sessions\ntype SessionOptions struct {\n\t// Name is the name of the session\n\tName string\n\n\t// Path is the path associated with the session\n\tPath string\n\n\t// Type is the type of the session (defaults to \"notebook\")\n\tType string\n\n\t// KernelName is the kernel name to use (e.g., python3, ir, etc.)\n\tKernelName string\n\n\t// KernelID is the ID of the existing kernel to reuse (if provided, KernelName will be ignored)\n\tKernelID string\n}\n\n// DefaultSessionType is the default session type\nconst DefaultSessionType = \"notebook\"\n" }, { "path": "components/execd/pkg/jupyter/transport.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage jupyter\n\nimport \"net/http\"\n\ntype AuthTransport struct {\n\tToken string\n\tBase http.RoundTripper\n}\n\nfunc (t *AuthTransport) RoundTrip(req *http.Request) (*http.Response, error) {\n\treqClone := req.Clone(req.Context())\n\treqClone.Header.Set(\"Authorization\", \"Token \"+t.Token)\n\treturn t.Base.RoundTrip(reqClone)\n}\n" }, { "path": "components/execd/pkg/log/log.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage log\n\nimport (\n\t\"os\"\n\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n)\n\nconst logFileEnvKey = \"EXECD_LOG_FILE\"\n\nvar current slogger.Logger\n\n// Init constructs the singleton logger. Call once during startup.\n// Legacy levels: 0/1/2=fatal, 3=error, 4=warn, 5/6=info, 7+=debug.\nfunc Init(level int) {\n\tcurrent = newLogger(mapLevel(level))\n}\n\nfunc mapLevel(level int) string {\n\tswitch {\n\tcase level <= 2:\n\t\treturn \"fatal\"\n\tcase level == 3:\n\t\treturn \"error\"\n\tcase level == 4:\n\t\treturn \"warn\"\n\tcase level == 5 || level == 6:\n\t\treturn \"info\"\n\tdefault:\n\t\treturn \"debug\"\n\t}\n}\n\nfunc newLogger(level string) slogger.Logger {\n\tcfg := slogger.Config{\n\t\tLevel: level,\n\t}\n\tif logFile := os.Getenv(logFileEnvKey); logFile != \"\" {\n\t\tcfg.OutputPaths = []string{logFile}\n\t\tcfg.ErrorOutputPaths = cfg.OutputPaths\n\t}\n\treturn slogger.MustNew(cfg)\n}\n\nfunc getLogger() slogger.Logger {\n\tif current != nil {\n\t\treturn current\n\t}\n\tl := newLogger(\"info\")\n\tcurrent = l\n\treturn l\n}\n\nfunc Debug(format string, args ...any) {\n\tgetLogger().Debugf(format, args...)\n}\n\nfunc Info(format string, args ...any) {\n\tgetLogger().Infof(format, args...)\n}\n\nfunc Warn(format string, args ...any) {\n\tgetLogger().Warnf(format, args...)\n}\n\n// Warning is an alias to Warn for compatibility.\nfunc Warning(format string, args ...any) {\n\tWarn(format, args...)\n}\n\nfunc Error(format string, args ...any) {\n\tgetLogger().Errorf(format, args...)\n}\n" }, { "path": "components/execd/pkg/runtime/bash_session.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build !windows\n// +build !windows\n\npackage runtime\n\nimport (\n\t\"bufio\"\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"os/exec\"\n\t\"sort\"\n\t\"strconv\"\n\t\"strings\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"github.com/google/uuid\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\nconst (\n\tenvDumpStartMarker = \"__ENV_DUMP_START__\"\n\tenvDumpEndMarker = \"__ENV_DUMP_END__\"\n\texitMarkerPrefix = \"__EXIT_CODE__:\"\n\tpwdMarkerPrefix = \"__PWD__:\"\n)\n\nfunc (c *Controller) createBashSession(req *CreateContextRequest) (string, error) {\n\tsession := newBashSession(req.Cwd)\n\tif err := session.start(); err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to start bash session: %w\", err)\n\t}\n\n\tc.bashSessionClientMap.Store(session.config.Session, session)\n\tlog.Info(\"created bash session %s\", session.config.Session)\n\treturn session.config.Session, nil\n}\n\nfunc (c *Controller) runBashSession(ctx context.Context, request *ExecuteCodeRequest) error {\n\tsession := c.getBashSession(request.Context)\n\tif session == nil {\n\t\treturn ErrContextNotFound\n\t}\n\n\treturn session.run(ctx, request)\n}\n\nfunc (c *Controller) getBashSession(sessionId string) *bashSession {\n\tif v, ok := c.bashSessionClientMap.Load(sessionId); ok {\n\t\tif s, ok := v.(*bashSession); ok {\n\t\t\treturn s\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (c *Controller) closeBashSession(sessionId string) error {\n\tsession := c.getBashSession(sessionId)\n\tif session == nil {\n\t\treturn ErrContextNotFound\n\t}\n\n\terr := session.close()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tc.bashSessionClientMap.Delete(sessionId)\n\treturn nil\n}\n\nfunc (c *Controller) CreateBashSession(req *CreateContextRequest) (string, error) {\n\treturn c.createBashSession(req)\n}\n\nfunc (c *Controller) RunInBashSession(ctx context.Context, req *ExecuteCodeRequest) error {\n\treturn c.runBashSession(ctx, req)\n}\n\nfunc (c *Controller) DeleteBashSession(sessionID string) error {\n\treturn c.closeBashSession(sessionID)\n}\n\n// Session implementation (pipe-based, no PTY)\nfunc newBashSession(cwd string) *bashSession {\n\tconfig := &bashSessionConfig{\n\t\tSession: uuidString(),\n\t\tStartupTimeout: 5 * time.Second,\n\t}\n\n\tenv := make(map[string]string)\n\tfor _, kv := range os.Environ() {\n\t\tif k, v, ok := splitEnvPair(kv); ok {\n\t\t\tenv[k] = v\n\t\t}\n\t}\n\n\treturn &bashSession{\n\t\tconfig: config,\n\t\tenv: env,\n\t\tcwd: cwd,\n\t}\n}\n\nfunc (s *bashSession) start() error {\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()\n\n\tif s.started {\n\t\treturn errors.New(\"session already started\")\n\t}\n\n\ts.started = true\n\treturn nil\n}\n\nfunc (s *bashSession) trackCurrentProcess(pid int) {\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()\n\ts.currentProcessPid = pid\n}\n\nfunc (s *bashSession) untrackCurrentProcess() {\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()\n\ts.currentProcessPid = 0\n}\n\n//nolint:gocognit\nfunc (s *bashSession) run(ctx context.Context, request *ExecuteCodeRequest) error {\n\ts.mu.Lock()\n\tif !s.started {\n\t\ts.mu.Unlock()\n\t\treturn errors.New(\"session not started\")\n\t}\n\n\tenvSnapshot := copyEnvMap(s.env)\n\n\tcwd := s.cwd\n\t// override original cwd if specified\n\tif request.Cwd != \"\" {\n\t\tcwd = request.Cwd\n\t}\n\tsessionID := s.config.Session\n\ts.mu.Unlock()\n\n\tstartAt := time.Now()\n\tif request.Hooks.OnExecuteInit != nil {\n\t\trequest.Hooks.OnExecuteInit(sessionID)\n\t}\n\n\twait := request.Timeout\n\tif wait <= 0 {\n\t\twait = 24 * 3600 * time.Second // max to 24 hours\n\t}\n\n\tctx, cancel := context.WithTimeout(ctx, wait)\n\tdefer cancel()\n\n\tscript := buildWrappedScript(request.Code, envSnapshot, cwd)\n\tscriptFile, err := os.CreateTemp(\"\", \"execd_bash_*.sh\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"create script file: %w\", err)\n\t}\n\tscriptPath := scriptFile.Name()\n\tif _, err := scriptFile.WriteString(script); err != nil {\n\t\t_ = scriptFile.Close()\n\t\treturn fmt.Errorf(\"write script file: %w\", err)\n\t}\n\tif err := scriptFile.Close(); err != nil {\n\t\treturn fmt.Errorf(\"close script file: %w\", err)\n\t}\n\n\tcmd := exec.CommandContext(ctx, \"bash\", \"--noprofile\", \"--norc\", scriptPath)\n\tcmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}\n\t// Do not pass envSnapshot via cmd.Env to avoid \"argument list too long\" when session env is large.\n\t// Child inherits parent env (nil => default in Go). The script file already has \"export K=V\" for\n\t// all session vars at the top, so the session environment is applied when the script runs.\n\tstdout, err := cmd.StdoutPipe()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"stdout pipe: %w\", err)\n\t}\n\tcmd.Stderr = cmd.Stdout\n\n\tif err := cmd.Start(); err != nil {\n\t\tlog.Error(\"start bash session failed: %v (command: %q)\", err, request.Code)\n\t\treturn fmt.Errorf(\"start bash: %w\", err)\n\t}\n\tdefer s.untrackCurrentProcess()\n\ts.trackCurrentProcess(cmd.Process.Pid)\n\n\tscanner := bufio.NewScanner(stdout)\n\tscanner.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)\n\n\tvar (\n\t\tenvLines []string\n\t\tpwdLine string\n\t\texitCode *int\n\t\tinEnv bool\n\t)\n\n\tfor scanner.Scan() {\n\t\tline := scanner.Text()\n\t\tswitch {\n\t\tcase line == envDumpStartMarker:\n\t\t\tinEnv = true\n\t\tcase line == envDumpEndMarker:\n\t\t\tinEnv = false\n\t\tcase strings.HasPrefix(line, exitMarkerPrefix):\n\t\t\tif code, err := strconv.Atoi(strings.TrimPrefix(line, exitMarkerPrefix)); err == nil {\n\t\t\t\texitCode = &code //nolint:ineffassign\n\t\t\t}\n\t\tcase strings.HasPrefix(line, pwdMarkerPrefix):\n\t\t\tpwdLine = strings.TrimPrefix(line, pwdMarkerPrefix)\n\t\tdefault:\n\t\t\tif inEnv {\n\t\t\t\tenvLines = append(envLines, line)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif request.Hooks.OnExecuteStdout != nil {\n\t\t\t\trequest.Hooks.OnExecuteStdout(line)\n\t\t\t}\n\t\t}\n\t}\n\n\tscanErr := scanner.Err()\n\twaitErr := cmd.Wait()\n\n\tif scanErr != nil {\n\t\tlog.Error(\"read stdout failed: %v (command: %q)\", scanErr, request.Code)\n\t\treturn fmt.Errorf(\"read stdout: %w\", scanErr)\n\t}\n\n\tif errors.Is(ctx.Err(), context.DeadlineExceeded) {\n\t\tlog.Error(\"timeout after %s while running command: %q\", wait, request.Code)\n\t\treturn fmt.Errorf(\"timeout after %s while running command %q\", wait, request.Code)\n\t}\n\n\tif exitCode == nil && cmd.ProcessState != nil {\n\t\tcode := cmd.ProcessState.ExitCode() //nolint:staticcheck\n\t\texitCode = &code //nolint:ineffassign\n\t}\n\n\tupdatedEnv := parseExportDump(envLines)\n\ts.mu.Lock()\n\tif len(updatedEnv) > 0 {\n\t\ts.env = updatedEnv\n\t}\n\tif pwdLine != \"\" {\n\t\ts.cwd = pwdLine\n\t}\n\ts.mu.Unlock()\n\n\tvar exitErr *exec.ExitError\n\tif waitErr != nil && !errors.As(waitErr, &exitErr) {\n\t\tlog.Error(\"command wait failed: %v (command: %q)\", waitErr, request.Code)\n\t\treturn waitErr\n\t}\n\n\tuserExitCode := 0\n\tif exitCode != nil {\n\t\tuserExitCode = *exitCode\n\t}\n\n\tif userExitCode != 0 {\n\t\terrMsg := fmt.Sprintf(\"command exited with code %d\", userExitCode)\n\t\tif waitErr != nil {\n\t\t\terrMsg = waitErr.Error()\n\t\t}\n\t\tif request.Hooks.OnExecuteError != nil {\n\t\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{\n\t\t\t\tEName: \"CommandExecError\",\n\t\t\t\tEValue: strconv.Itoa(userExitCode),\n\t\t\t\tTraceback: []string{errMsg},\n\t\t\t})\n\t\t}\n\t\tlog.Error(\"CommandExecError: %s (command: %q)\", errMsg, request.Code)\n\t\treturn nil\n\t}\n\n\tif request.Hooks.OnExecuteComplete != nil {\n\t\trequest.Hooks.OnExecuteComplete(time.Since(startAt))\n\t}\n\n\treturn nil\n}\n\nfunc buildWrappedScript(command string, env map[string]string, cwd string) string {\n\tvar b strings.Builder\n\n\tkeys := make([]string, 0, len(env))\n\tfor k := range env {\n\t\tv := env[k]\n\t\tif isValidEnvKey(k) && !envKeysNotPersisted[k] && len(v) <= maxPersistedEnvValueSize {\n\t\t\tkeys = append(keys, k)\n\t\t}\n\t}\n\tsort.Strings(keys)\n\tfor _, k := range keys {\n\t\tb.WriteString(\"export \")\n\t\tb.WriteString(k)\n\t\tb.WriteString(\"=\")\n\t\tb.WriteString(shellEscape(env[k]))\n\t\tb.WriteString(\"\\n\")\n\t}\n\n\tif cwd != \"\" {\n\t\tb.WriteString(\"cd \")\n\t\tb.WriteString(shellEscape(cwd))\n\t\tb.WriteString(\"\\n\")\n\t}\n\n\tb.WriteString(command)\n\tif !strings.HasSuffix(command, \"\\n\") {\n\t\tb.WriteString(\"\\n\")\n\t}\n\n\tb.WriteString(\"__USER_EXIT_CODE__=$?\\n\")\n\tb.WriteString(\"printf \\\"\\\\n%s\\\\n\\\" \\\"\" + envDumpStartMarker + \"\\\"\\n\")\n\tb.WriteString(\"export -p\\n\")\n\tb.WriteString(\"printf \\\"%s\\\\n\\\" \\\"\" + envDumpEndMarker + \"\\\"\\n\")\n\tb.WriteString(\"printf \\\"\" + pwdMarkerPrefix + \"%s\\\\n\\\" \\\"$(pwd)\\\"\\n\")\n\tb.WriteString(\"printf \\\"\" + exitMarkerPrefix + \"%s\\\\n\\\" \\\"$__USER_EXIT_CODE__\\\"\\n\")\n\tb.WriteString(\"exit \\\"$__USER_EXIT_CODE__\\\"\\n\")\n\n\treturn b.String()\n}\n\n// envKeysNotPersisted are not carried across runs (prompt/display vars).\nvar envKeysNotPersisted = map[string]bool{\n\t\"PS1\": true, \"PS2\": true, \"PS3\": true, \"PS4\": true,\n\t\"PROMPT_COMMAND\": true,\n}\n\n// maxPersistedEnvValueSize caps single env value length as a safeguard.\nconst maxPersistedEnvValueSize = 8 * 1024\n\nfunc parseExportDump(lines []string) map[string]string {\n\tif len(lines) == 0 {\n\t\treturn nil\n\t}\n\tenv := make(map[string]string, len(lines))\n\tfor _, line := range lines {\n\t\tk, v, ok := parseExportLine(line)\n\t\tif !ok || envKeysNotPersisted[k] || len(v) > maxPersistedEnvValueSize {\n\t\t\tcontinue\n\t\t}\n\t\tenv[k] = v\n\t}\n\treturn env\n}\n\nfunc parseExportLine(line string) (string, string, bool) {\n\tconst prefix = \"declare -x \"\n\tif !strings.HasPrefix(line, prefix) {\n\t\treturn \"\", \"\", false\n\t}\n\trest := strings.TrimSpace(strings.TrimPrefix(line, prefix))\n\tif rest == \"\" {\n\t\treturn \"\", \"\", false\n\t}\n\tname, value := rest, \"\"\n\tif eq := strings.Index(rest, \"=\"); eq >= 0 {\n\t\tname = rest[:eq]\n\t\traw := rest[eq+1:]\n\t\tif unquoted, err := strconv.Unquote(raw); err == nil {\n\t\t\tvalue = unquoted\n\t\t} else {\n\t\t\tvalue = strings.Trim(raw, `\"`)\n\t\t}\n\t}\n\tif !isValidEnvKey(name) {\n\t\treturn \"\", \"\", false\n\t}\n\treturn name, value, true\n}\n\nfunc shellEscape(value string) string {\n\treturn \"'\" + strings.ReplaceAll(value, \"'\", `'\"'\"'`) + \"'\"\n}\n\nfunc isValidEnvKey(key string) bool {\n\tif key == \"\" {\n\t\treturn false\n\t}\n\n\tfor i, r := range key {\n\t\tif i == 0 {\n\t\t\tif (r < 'A' || (r > 'Z' && r < 'a') || r > 'z') && r != '_' {\n\t\t\t\treturn false\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tif (r < 'A' || (r > 'Z' && r < 'a') || r > 'z') && (r < '0' || r > '9') && r != '_' {\n\t\t\treturn false\n\t\t}\n\t}\n\n\treturn true\n}\n\nfunc copyEnvMap(src map[string]string) map[string]string {\n\tif src == nil {\n\t\treturn map[string]string{}\n\t}\n\n\tdst := make(map[string]string, len(src))\n\tfor k, v := range src {\n\t\tdst[k] = v\n\t}\n\treturn dst\n}\n\nfunc splitEnvPair(kv string) (string, string, bool) {\n\tparts := strings.SplitN(kv, \"=\", 2)\n\tif len(parts) != 2 {\n\t\treturn \"\", \"\", false\n\t}\n\tif !isValidEnvKey(parts[0]) {\n\t\treturn \"\", \"\", false\n\t}\n\treturn parts[0], parts[1], true\n}\n\nfunc (s *bashSession) close() error {\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()\n\n\tpid := s.currentProcessPid\n\ts.currentProcessPid = 0\n\ts.started = false\n\ts.env = nil\n\ts.cwd = \"\"\n\n\tif pid != 0 {\n\t\tif err := syscall.Kill(-pid, syscall.SIGKILL); err != nil {\n\t\t\tlog.Warning(\"kill session process group %d: %v (process may have already exited)\", pid, err)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc uuidString() string {\n\treturn uuid.New().String()\n}\n" }, { "path": "components/execd/pkg/runtime/bash_session_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build !windows\n// +build !windows\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"os/exec\"\n\t\"strings\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/stretchr/testify/assert\"\n\t\"github.com/stretchr/testify/require\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n)\n\nfunc TestBashSession_NonZeroExitEmitsError(t *testing.T) {\n\tif _, err := exec.LookPath(\"bash\"); err != nil {\n\t\tt.Skip(\"bash not found in PATH\")\n\t}\n\n\tc := NewController(\"\", \"\")\n\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\tvar (\n\t\tsessionID string\n\t\tstdoutLine string\n\t\terrCh = make(chan *execute.ErrorOutput, 1)\n\t\tcompleteCh = make(chan struct{}, 1)\n\t)\n\n\treq := &ExecuteCodeRequest{\n\t\tLanguage: Bash,\n\t\tCode: `echo \"before\"; exit 7`,\n\t\tCwd: t.TempDir(),\n\t\tTimeout: 5 * time.Second,\n\t\tHooks: ExecuteResultHook{\n\t\t\tOnExecuteInit: func(s string) { sessionID = s },\n\t\t\tOnExecuteStdout: func(s string) { stdoutLine = s },\n\t\t\tOnExecuteError: func(err *execute.ErrorOutput) { errCh <- err },\n\t\t\tOnExecuteComplete: func(_ time.Duration) {\n\t\t\t\tcompleteCh <- struct{}{}\n\t\t\t},\n\t\t},\n\t}\n\n\tsession, err := c.createBashSession(&CreateContextRequest{})\n\tassert.NoError(t, err)\n\treq.Context = session\n\trequire.NoError(t, c.runBashSession(ctx, req))\n\n\tvar gotErr *execute.ErrorOutput\n\tselect {\n\tcase gotErr = <-errCh:\n\tcase <-time.After(2 * time.Second):\n\t\trequire.Fail(t, \"expected error hook to be called\")\n\t}\n\trequire.NotNil(t, gotErr, \"expected non-nil error output\")\n\trequire.Equal(t, \"CommandExecError\", gotErr.EName)\n\trequire.Equal(t, \"7\", gotErr.EValue)\n\trequire.NotEmpty(t, sessionID, \"expected session id to be set\")\n\trequire.Equal(t, \"before\", stdoutLine)\n\n\tselect {\n\tcase <-completeCh:\n\t\trequire.Fail(t, \"did not expect completion hook on non-zero exit\")\n\tdefault:\n\t}\n}\n\nfunc TestBashSession_envAndExitCode(t *testing.T) {\n\tsession := newBashSession(\"\")\n\tt.Cleanup(func() { _ = session.close() })\n\n\trequire.NoError(t, session.start())\n\n\tvar (\n\t\tinitCalls int\n\t\tcompleteCalls int\n\t\tstdoutLines []string\n\t)\n\n\thooks := ExecuteResultHook{\n\t\tOnExecuteInit: func(ctx string) {\n\t\t\trequire.Equal(t, session.config.Session, ctx, \"unexpected session in OnExecuteInit\")\n\t\t\tinitCalls++\n\t\t},\n\t\tOnExecuteStdout: func(text string) {\n\t\t\tt.Log(text)\n\t\t\tstdoutLines = append(stdoutLines, text)\n\t\t},\n\t\tOnExecuteComplete: func(_ time.Duration) {\n\t\t\tcompleteCalls++\n\t\t},\n\t}\n\n\t// 1) export an env var\n\trequest := &ExecuteCodeRequest{\n\t\tCode: \"export FOO=hello\",\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t}\n\trequire.NoError(t, session.run(context.Background(), request))\n\texportStdoutCount := len(stdoutLines)\n\n\t// 2) verify env is persisted\n\trequest = &ExecuteCodeRequest{\n\t\tCode: \"echo $FOO\",\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t}\n\trequire.NoError(t, session.run(context.Background(), request))\n\techoLines := stdoutLines[exportStdoutCount:]\n\tfoundHello := false\n\tfor _, line := range echoLines {\n\t\tif strings.TrimSpace(line) == \"hello\" {\n\t\t\tfoundHello = true\n\t\t\tbreak\n\t\t}\n\t}\n\trequire.True(t, foundHello, \"expected echo $FOO to output 'hello', got %v\", echoLines)\n\n\t// 3) ensure exit code of previous command is reflected in shell state\n\trequest = &ExecuteCodeRequest{\n\t\tCode: \"false; echo EXIT:$?\",\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t}\n\tprevCount := len(stdoutLines)\n\trequire.NoError(t, session.run(context.Background(), request))\n\texitLines := stdoutLines[prevCount:]\n\tfoundExit := false\n\tfor _, line := range exitLines {\n\t\tif strings.Contains(line, \"EXIT:1\") {\n\t\t\tfoundExit = true\n\t\t\tbreak\n\t\t}\n\t}\n\trequire.True(t, foundExit, \"expected exit code output 'EXIT:1', got %v\", exitLines)\n\trequire.Equal(t, 3, initCalls, \"OnExecuteInit expected 3 calls\")\n\trequire.Equal(t, 3, completeCalls, \"OnExecuteComplete expected 3 calls\")\n}\n\nfunc TestBashSession_envLargeOutputChained(t *testing.T) {\n\tsession := newBashSession(\"\")\n\tt.Cleanup(func() { _ = session.close() })\n\n\trequire.NoError(t, session.start())\n\n\tvar (\n\t\tinitCalls int\n\t\tcompleteCalls int\n\t\tstdoutLines []string\n\t)\n\n\thooks := ExecuteResultHook{\n\t\tOnExecuteInit: func(ctx string) {\n\t\t\trequire.Equal(t, session.config.Session, ctx, \"unexpected session in OnExecuteInit\")\n\t\t\tinitCalls++\n\t\t},\n\t\tOnExecuteStdout: func(text string) {\n\t\t\tt.Log(text)\n\t\t\tstdoutLines = append(stdoutLines, text)\n\t\t},\n\t\tOnExecuteComplete: func(_ time.Duration) {\n\t\t\tcompleteCalls++\n\t\t},\n\t}\n\n\trunAndCollect := func(cmd string) []string {\n\t\tstart := len(stdoutLines)\n\t\trequest := &ExecuteCodeRequest{\n\t\t\tCode: cmd,\n\t\t\tHooks: hooks,\n\t\t\tTimeout: 10 * time.Second,\n\t\t}\n\t\trequire.NoError(t, session.run(context.Background(), request))\n\t\treturn append([]string(nil), stdoutLines[start:]...)\n\t}\n\n\tlines1 := runAndCollect(\"export FOO=hello1; for i in $(seq 1 60); do echo A${i}:$FOO; done\")\n\trequire.GreaterOrEqual(t, len(lines1), 60, \"expected >=60 lines for cmd1\")\n\trequire.True(t, containsLine(lines1, \"A1:hello1\") && containsLine(lines1, \"A60:hello1\"), \"env not reflected in cmd1 output, got %v\", lines1[:3])\n\n\tlines2 := runAndCollect(\"export FOO=${FOO}_next; export BAR=bar1; for i in $(seq 1 60); do echo B${i}:$FOO:$BAR; done\")\n\trequire.GreaterOrEqual(t, len(lines2), 60, \"expected >=60 lines for cmd2\")\n\trequire.True(t, containsLine(lines2, \"B1:hello1_next:bar1\") && containsLine(lines2, \"B60:hello1_next:bar1\"), \"env not propagated to cmd2 output, sample %v\", lines2[:3])\n\n\tlines3 := runAndCollect(\"export BAR=${BAR}_last; for i in $(seq 1 60); do echo C${i}:$FOO:$BAR; done; echo FINAL_FOO=$FOO; echo FINAL_BAR=$BAR\")\n\trequire.GreaterOrEqual(t, len(lines3), 62, \"expected >=62 lines for cmd3\") // 60 lines + 2 finals\n\trequire.True(t, containsLine(lines3, \"C1:hello1_next:bar1_last\") && containsLine(lines3, \"C60:hello1_next:bar1_last\"), \"env not propagated to cmd3 output, sample %v\", lines3[:3])\n\trequire.True(t, containsLine(lines3, \"FINAL_FOO=hello1_next\") && containsLine(lines3, \"FINAL_BAR=bar1_last\"), \"final env lines missing, got %v\", lines3[len(lines3)-5:])\n\trequire.Equal(t, 3, initCalls, \"OnExecuteInit expected 3 calls\")\n\trequire.Equal(t, 3, completeCalls, \"OnExecuteComplete expected 3 calls\")\n}\n\nfunc TestBashSession_cwdPersistsWithoutOverride(t *testing.T) {\n\tsession := newBashSession(\"\")\n\tt.Cleanup(func() { _ = session.close() })\n\n\trequire.NoError(t, session.start())\n\n\ttargetDir := t.TempDir()\n\tvar stdoutLines []string\n\thooks := ExecuteResultHook{\n\t\tOnExecuteStdout: func(line string) {\n\t\t\tstdoutLines = append(stdoutLines, line)\n\t\t},\n\t}\n\n\trunAndCollect := func(req *ExecuteCodeRequest) []string {\n\t\tstart := len(stdoutLines)\n\t\trequire.NoError(t, session.run(context.Background(), req))\n\t\treturn append([]string(nil), stdoutLines[start:]...)\n\t}\n\n\tfirstRunLines := runAndCollect(&ExecuteCodeRequest{\n\t\tCode: fmt.Sprintf(\"cd %s\\npwd\", targetDir),\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t})\n\trequire.True(t, containsLine(firstRunLines, targetDir), \"expected cd to update cwd to %q, got %v\", targetDir, firstRunLines)\n\n\tsecondRunLines := runAndCollect(&ExecuteCodeRequest{\n\t\tCode: \"pwd\",\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t})\n\trequire.True(t, containsLine(secondRunLines, targetDir), \"expected subsequent run to inherit cwd %q, got %v\", targetDir, secondRunLines)\n\n\tsession.mu.Lock()\n\tfinalCwd := session.cwd\n\tsession.mu.Unlock()\n\trequire.Equal(t, targetDir, finalCwd, \"expected session cwd to stay at %q\", targetDir)\n}\n\nfunc TestBashSession_requestCwdOverridesAfterCd(t *testing.T) {\n\tsession := newBashSession(\"\")\n\tt.Cleanup(func() { _ = session.close() })\n\n\trequire.NoError(t, session.start())\n\n\tinitialDir := t.TempDir()\n\toverrideDir := t.TempDir()\n\n\tvar stdoutLines []string\n\thooks := ExecuteResultHook{\n\t\tOnExecuteStdout: func(line string) {\n\t\t\tstdoutLines = append(stdoutLines, line)\n\t\t},\n\t}\n\n\trunAndCollect := func(req *ExecuteCodeRequest) []string {\n\t\tstart := len(stdoutLines)\n\t\trequire.NoError(t, session.run(context.Background(), req))\n\t\treturn append([]string(nil), stdoutLines[start:]...)\n\t}\n\n\t// First request: change session cwd via script.\n\tfirstRunLines := runAndCollect(&ExecuteCodeRequest{\n\t\tCode: fmt.Sprintf(\"cd %s\\npwd\", initialDir),\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t})\n\trequire.True(t, containsLine(firstRunLines, initialDir), \"expected cd to update cwd to %q, got %v\", initialDir, firstRunLines)\n\n\t// Second request: explicit Cwd overrides session cwd.\n\tsecondRunLines := runAndCollect(&ExecuteCodeRequest{\n\t\tCode: \"pwd\",\n\t\tCwd: overrideDir,\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t})\n\trequire.True(t, containsLine(secondRunLines, overrideDir), \"expected command to run in override cwd %q, got %v\", overrideDir, secondRunLines)\n\n\tsession.mu.Lock()\n\tfinalCwd := session.cwd\n\tsession.mu.Unlock()\n\trequire.Equal(t, overrideDir, finalCwd, \"expected session cwd updated to override dir %q\", overrideDir)\n}\n\nfunc TestBashSession_envDumpNotLeakedWhenNoTrailingNewline(t *testing.T) {\n\tsession := newBashSession(\"\")\n\tt.Cleanup(func() { _ = session.close() })\n\n\trequire.NoError(t, session.start())\n\n\tvar stdoutLines []string\n\thooks := ExecuteResultHook{\n\t\tOnExecuteStdout: func(line string) {\n\t\t\tstdoutLines = append(stdoutLines, line)\n\t\t},\n\t}\n\n\trequest := &ExecuteCodeRequest{\n\t\tCode: `set +x; printf '{\"foo\":1}'`,\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t}\n\trequire.NoError(t, session.run(context.Background(), request))\n\n\trequire.Len(t, stdoutLines, 1, \"expected exactly one stdout line\")\n\trequire.Equal(t, `{\"foo\":1}`, strings.TrimSpace(stdoutLines[0]))\n\tfor _, line := range stdoutLines {\n\t\trequire.NotContains(t, line, envDumpStartMarker, \"env dump leaked into stdout: %v\", stdoutLines)\n\t\trequire.NotContains(t, line, \"declare -x\", \"env dump leaked into stdout: %v\", stdoutLines)\n\t}\n}\n\nfunc TestBashSession_envDumpNotLeakedWhenNoOutput(t *testing.T) {\n\tsession := newBashSession(\"\")\n\tt.Cleanup(func() { _ = session.close() })\n\n\trequire.NoError(t, session.start())\n\n\tvar stdoutLines []string\n\thooks := ExecuteResultHook{\n\t\tOnExecuteStdout: func(line string) {\n\t\t\tstdoutLines = append(stdoutLines, line)\n\t\t},\n\t}\n\n\trequest := &ExecuteCodeRequest{\n\t\tCode: `set +x; true`,\n\t\tHooks: hooks,\n\t\tTimeout: 3 * time.Second,\n\t}\n\trequire.NoError(t, session.run(context.Background(), request))\n\n\trequire.LessOrEqual(t, len(stdoutLines), 1, \"expected at most one stdout line, got %v\", stdoutLines)\n\tif len(stdoutLines) == 1 {\n\t\trequire.Empty(t, strings.TrimSpace(stdoutLines[0]), \"expected empty stdout\")\n\t}\n\tfor _, line := range stdoutLines {\n\t\trequire.NotContains(t, line, envDumpStartMarker, \"env dump leaked into stdout: %v\", stdoutLines)\n\t\trequire.NotContains(t, line, \"declare -x\", \"env dump leaked into stdout: %v\", stdoutLines)\n\t}\n}\n\nfunc TestBashSession_heredoc(t *testing.T) {\n\trewardDir := t.TempDir()\n\tcontroller := NewController(\"\", \"\")\n\n\tsessionID, err := controller.CreateBashSession(&CreateContextRequest{})\n\trequire.NoError(t, err)\n\tt.Cleanup(func() { _ = controller.DeleteBashSession(sessionID) })\n\n\thooks := ExecuteResultHook{\n\t\tOnExecuteStdout: func(line string) {\n\t\t\tfmt.Printf(\"[stdout] %s\\n\", line)\n\t\t},\n\t\tOnExecuteComplete: func(d time.Duration) {\n\t\t\tfmt.Printf(\"[complete] %s\\n\", d)\n\t\t},\n\t}\n\n\t// First run: heredoc + reward file write.\n\tscript := fmt.Sprintf(`\nset -x\nreward_dir=%q\nmkdir -p \"$reward_dir\"\n\ncat > /tmp/repro_script.sh <<'SHEOF'\n#!/usr/bin/env sh\necho \"hello heredoc\"\nSHEOF\n\nchmod +x /tmp/repro_script.sh\n/tmp/repro_script.sh\necho \"after heredoc\"\necho 1 > \"$reward_dir/reward.txt\"\ncat \"$reward_dir/reward.txt\"\n`, rewardDir)\n\n\tctx := context.Background()\n\trequire.NoError(t, controller.RunInBashSession(ctx, &ExecuteCodeRequest{\n\t\tContext: sessionID,\n\t\tLanguage: Bash,\n\t\tTimeout: 10 * time.Second,\n\t\tCode: script,\n\t\tHooks: hooks,\n\t}))\n\n\t// Second run: ensure the session keeps working.\n\trequire.NoError(t, controller.RunInBashSession(ctx, &ExecuteCodeRequest{\n\t\tContext: sessionID,\n\t\tLanguage: Bash,\n\t\tTimeout: 5 * time.Second,\n\t\tCode: \"echo 'second command works'\",\n\t\tHooks: hooks,\n\t}))\n}\n\nfunc TestBashSession_execReplacesShell(t *testing.T) {\n\tsession := newBashSession(\"\")\n\tt.Cleanup(func() { _ = session.close() })\n\n\trequire.NoError(t, session.start())\n\n\tvar stdoutLines []string\n\thooks := ExecuteResultHook{\n\t\tOnExecuteStdout: func(line string) {\n\t\t\tstdoutLines = append(stdoutLines, line)\n\t\t},\n\t}\n\n\tscript := `\ncat > /tmp/exec_child.sh <<'EOF'\necho \"child says hi\"\nEOF\nchmod +x /tmp/exec_child.sh\nexec /tmp/exec_child.sh\n`\n\n\trequest := &ExecuteCodeRequest{\n\t\tCode: script,\n\t\tHooks: hooks,\n\t\tTimeout: 5 * time.Second,\n\t}\n\trequire.NoError(t, session.run(context.Background(), request), \"expected exec to complete without killing the session\")\n\trequire.True(t, containsLine(stdoutLines, \"child says hi\"), \"expected child output, got %v\", stdoutLines)\n\n\t// Subsequent run should still work because we restart bash per run.\n\trequest = &ExecuteCodeRequest{\n\t\tCode: \"echo still-alive\",\n\t\tHooks: hooks,\n\t\tTimeout: 2 * time.Second,\n\t}\n\tstdoutLines = nil\n\trequire.NoError(t, session.run(context.Background(), request), \"expected run to succeed after exec replaced the shell\")\n\trequire.True(t, containsLine(stdoutLines, \"still-alive\"), \"expected follow-up output, got %v\", stdoutLines)\n}\n\nfunc TestBashSession_complexExec(t *testing.T) {\n\tsession := newBashSession(\"\")\n\tt.Cleanup(func() { _ = session.close() })\n\n\trequire.NoError(t, session.start())\n\n\tvar stdoutLines []string\n\thooks := ExecuteResultHook{\n\t\tOnExecuteStdout: func(line string) {\n\t\t\tstdoutLines = append(stdoutLines, line)\n\t\t},\n\t}\n\n\tscript := `\nLOG_FILE=$(mktemp)\nexport LOG_FILE\nexec 3>&1 4>&2\nexec > >(tee \"$LOG_FILE\") 2>&1\n\nset -x\necho \"from-complex-exec\"\nexec 1>&3 2>&4 # step record\necho \"after-restore\"\n`\n\n\trequest := &ExecuteCodeRequest{\n\t\tCode: script,\n\t\tHooks: hooks,\n\t\tTimeout: 5 * time.Second,\n\t}\n\trequire.NoError(t, session.run(context.Background(), request), \"expected complex exec to finish\")\n\trequire.True(t, containsLine(stdoutLines, \"from-complex-exec\") && containsLine(stdoutLines, \"after-restore\"), \"expected exec outputs, got %v\", stdoutLines)\n\n\t// Session should still be usable.\n\trequest = &ExecuteCodeRequest{\n\t\tCode: \"echo still-alive\",\n\t\tHooks: hooks,\n\t\tTimeout: 2 * time.Second,\n\t}\n\tstdoutLines = nil\n\trequire.NoError(t, session.run(context.Background(), request), \"expected run to succeed after complex exec\")\n\trequire.True(t, containsLine(stdoutLines, \"still-alive\"), \"expected follow-up output, got %v\", stdoutLines)\n}\n\nfunc containsLine(lines []string, target string) bool {\n\tfor _, l := range lines {\n\t\tif strings.TrimSpace(l) == target {\n\t\t\treturn true\n\t\t}\n\t}\n\treturn false\n}\n\n// TestBashSession_CloseKillsRunningProcess verifies that session.close() kills the active\n// process group so that a long-running command (e.g. sleep) does not keep running after close.\nfunc TestBashSession_CloseKillsRunningProcess(t *testing.T) {\n\tif _, err := exec.LookPath(\"bash\"); err != nil {\n\t\tt.Skip(\"bash not found in PATH\")\n\t}\n\n\tsession := newBashSession(\"\")\n\trequire.NoError(t, session.start())\n\n\trunDone := make(chan error, 1)\n\treq := &ExecuteCodeRequest{\n\t\tCode: \"sleep 30\",\n\t\tTimeout: 60 * time.Second,\n\t\tHooks: ExecuteResultHook{},\n\t}\n\tgo func() {\n\t\trunDone <- session.run(context.Background(), req)\n\t}()\n\n\t// Give the child process time to start.\n\ttime.Sleep(200 * time.Millisecond)\n\n\t// Close should kill the process group; run() should return soon (it may return nil\n\t// because the code path treats non-zero exit as success after calling OnExecuteError).\n\trequire.NoError(t, session.close())\n\n\tselect {\n\tcase <-runDone:\n\t\t// run() returned; process was killed so we did not wait 30s\n\tcase <-time.After(3 * time.Second):\n\t\trequire.Fail(t, \"run did not return within 3s after close (process was not killed)\")\n\t}\n}\n\n// TestBashSession_DeleteBashSessionKillsRunningProcess verifies that DeleteBashSession\n// (close path) kills the active run and removes the session from the controller.\nfunc TestBashSession_DeleteBashSessionKillsRunningProcess(t *testing.T) {\n\tif _, err := exec.LookPath(\"bash\"); err != nil {\n\t\tt.Skip(\"bash not found in PATH\")\n\t}\n\n\tc := NewController(\"\", \"\")\n\tsessionID, err := c.CreateBashSession(&CreateContextRequest{})\n\trequire.NoError(t, err)\n\n\trunDone := make(chan error, 1)\n\treq := &ExecuteCodeRequest{\n\t\tLanguage: Bash,\n\t\tContext: sessionID,\n\t\tCode: \"sleep 30\",\n\t\tTimeout: 60 * time.Second,\n\t\tHooks: ExecuteResultHook{},\n\t}\n\tgo func() {\n\t\trunDone <- c.RunInBashSession(context.Background(), req)\n\t}()\n\n\ttime.Sleep(200 * time.Millisecond)\n\n\trequire.NoError(t, c.DeleteBashSession(sessionID))\n\n\tselect {\n\tcase <-runDone:\n\t\t// RunInBashSession returned; process was killed\n\tcase <-time.After(3 * time.Second):\n\t\trequire.Fail(t, \"RunInBashSession did not return within 3s after DeleteBashSession\")\n\t}\n\n\t// Session should be gone; deleting again should return ErrContextNotFound.\n\terr = c.DeleteBashSession(sessionID)\n\trequire.Error(t, err)\n\trequire.ErrorIs(t, err, ErrContextNotFound)\n}\n\n// TestBashSession_CloseWithNoActiveRun verifies that close() with no running command\n// completes without error and does not hang.\nfunc TestBashSession_CloseWithNoActiveRun(t *testing.T) {\n\tsession := newBashSession(\"\")\n\trequire.NoError(t, session.start())\n\n\tdone := make(chan struct{}, 1)\n\tgo func() {\n\t\t_ = session.close()\n\t\tdone <- struct{}{}\n\t}()\n\n\tselect {\n\tcase <-done:\n\t\t// close() returned\n\tcase <-time.After(2 * time.Second):\n\t\trequire.Fail(t, \"close() did not return within 2s when no run was active\")\n\t}\n}\n" }, { "path": "components/execd/pkg/runtime/bash_session_windows.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build windows\n// +build windows\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"errors\"\n)\n\nvar errBashSessionNotSupported = errors.New(\"bash session is not supported on windows\")\n\n// CreateBashSession is not supported on Windows.\nfunc (c *Controller) CreateBashSession(_ *CreateContextRequest) (string, error) { //nolint:revive\n\treturn \"\", errBashSessionNotSupported\n}\n\n// RunInBashSession is not supported on Windows.\nfunc (c *Controller) RunInBashSession(_ context.Context, _ *ExecuteCodeRequest) error { //nolint:revive\n\treturn errBashSessionNotSupported\n}\n\n// DeleteBashSession is not supported on Windows.\nfunc (c *Controller) DeleteBashSession(_ string) error { //nolint:revive\n\treturn errBashSessionNotSupported\n}\n" }, { "path": "components/execd/pkg/runtime/command.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build !windows\n// +build !windows\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"os/exec\"\n\t\"os/signal\"\n\t\"os/user\"\n\t\"strconv\"\n\t\"sync\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/util/safego\"\n)\n\n// getShell returns the preferred shell, falling back to sh if bash is not available.\n// This is needed for Alpine-based Docker images that only have sh by default.\nfunc getShell() string {\n\tif _, err := exec.LookPath(\"bash\"); err == nil {\n\t\treturn \"bash\"\n\t}\n\treturn \"sh\"\n}\n\nfunc buildCredential(uid, gid *uint32) (*syscall.Credential, error) {\n\tif uid == nil && gid == nil {\n\t\treturn nil, nil //nolint:nilnil\n\t}\n\n\tcred := &syscall.Credential{}\n\tif uid != nil {\n\t\tcred.Uid = *uid\n\t\t// Load user info to get primary GID and supplemental groups\n\t\tu, err := user.LookupId(strconv.FormatUint(uint64(*uid), 10))\n\t\tif err == nil {\n\t\t\t// Set primary GID if not explicitly provided\n\t\t\tif gid == nil {\n\t\t\t\tprimaryGid, err := strconv.ParseUint(u.Gid, 10, 32)\n\t\t\t\tif err == nil {\n\t\t\t\t\tcred.Gid = uint32(primaryGid)\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Load supplemental groups\n\t\t\tgids, err := u.GroupIds()\n\t\t\tif err == nil {\n\t\t\t\tfor _, g := range gids {\n\t\t\t\t\tid, err := strconv.ParseUint(g, 10, 32)\n\t\t\t\t\tif err == nil {\n\t\t\t\t\t\tcred.Groups = append(cred.Groups, uint32(id))\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t// Override Gid if explicitly provided\n\tif gid != nil {\n\t\tcred.Gid = *gid\n\t}\n\n\treturn cred, nil\n}\n\n// runCommand executes shell commands and streams their output.\nfunc (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest) error {\n\tsession := c.newContextID()\n\n\tsignals := make(chan os.Signal, 1)\n\tdefer close(signals)\n\tsignal.Notify(signals)\n\tdefer signal.Reset()\n\n\tstdout, stderr, err := c.stdLogDescriptor(session)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to get stdlog descriptor: %w\", err)\n\t}\n\tdefer stdout.Close()\n\tdefer stderr.Close()\n\tstdoutPath := c.stdoutFileName(session)\n\tstderrPath := c.stderrFileName(session)\n\n\tstartAt := time.Now()\n\tlog.Info(\"received command: %v\", request.Code)\n\tshell := getShell()\n\tcmd := exec.CommandContext(ctx, shell, \"-c\", request.Code)\n\n\t// Configure credentials and process group\n\tcred, err := buildCredential(request.Uid, request.Gid)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to build credential: %w\", err)\n\t}\n\tcmd.SysProcAttr = &syscall.SysProcAttr{\n\t\tSetpgid: true,\n\t\tCredential: cred,\n\t}\n\n\tcmd.Stdout = stdout\n\tcmd.Stderr = stderr\n\textraEnv := mergeExtraEnvs(loadExtraEnvFromFile(), request.Envs)\n\tcmd.Env = mergeEnvs(os.Environ(), extraEnv)\n\tcmd.Dir = request.Cwd\n\n\tdone := make(chan struct{}, 1)\n\tvar wg sync.WaitGroup\n\twg.Add(2)\n\tsafego.Go(func() {\n\t\tdefer wg.Done()\n\t\tc.tailStdPipe(stdoutPath, request.Hooks.OnExecuteStdout, done)\n\t})\n\tsafego.Go(func() {\n\t\tdefer wg.Done()\n\t\tc.tailStdPipe(stderrPath, request.Hooks.OnExecuteStderr, done)\n\t})\n\n\terr = cmd.Start()\n\tif err != nil {\n\t\tclose(done)\n\t\twg.Wait()\n\t\trequest.Hooks.OnExecuteInit(session)\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"CommandExecError\", EValue: err.Error()})\n\t\tlog.Error(\"CommandExecError: error starting commands: %v\", err)\n\t\treturn nil\n\t}\n\n\tkernel := &commandKernel{\n\t\tpid: cmd.Process.Pid,\n\t\tstdoutPath: stdoutPath,\n\t\tstderrPath: stderrPath,\n\t\tstartedAt: startAt,\n\t\trunning: true,\n\t\tcontent: request.Code,\n\t\tisBackground: false,\n\t}\n\tc.storeCommandKernel(session, kernel)\n\trequest.Hooks.OnExecuteInit(session)\n\n\tgo func() {\n\t\tfor {\n\t\t\tselect {\n\t\t\tcase <-ctx.Done():\n\t\t\t\treturn\n\t\t\tcase sig := <-signals:\n\t\t\t\tif sig == nil {\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t\t// DO NOT forward syscall.SIGURG to children processes.\n\t\t\t\tif sig != syscall.SIGCHLD && sig != syscall.SIGURG {\n\t\t\t\t\t_ = syscall.Kill(-cmd.Process.Pid, sig.(syscall.Signal))\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}()\n\n\terr = cmd.Wait()\n\tclose(done)\n\twg.Wait()\n\tif err != nil {\n\t\tvar eName, eValue string\n\t\tvar eCode int\n\t\tvar traceback []string\n\n\t\tvar exitError *exec.ExitError\n\t\tif errors.As(err, &exitError) {\n\t\t\texitCode := exitError.ExitCode()\n\t\t\teName = \"CommandExecError\"\n\t\t\teValue = strconv.Itoa(exitCode)\n\t\t\teCode = exitCode\n\t\t} else {\n\t\t\teName = \"CommandExecError\"\n\t\t\teValue = err.Error()\n\t\t\teCode = 1\n\t\t}\n\t\ttraceback = []string{err.Error()}\n\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{\n\t\t\tEName: eName,\n\t\t\tEValue: eValue,\n\t\t\tTraceback: traceback,\n\t\t})\n\n\t\tlog.Error(\"CommandExecError: error running commands: %v\", err)\n\t\tc.markCommandFinished(session, eCode, err.Error())\n\t\treturn nil\n\t}\n\n\tc.markCommandFinished(session, 0, \"\")\n\trequest.Hooks.OnExecuteComplete(time.Since(startAt))\n\treturn nil\n}\n\n// runBackgroundCommand executes shell commands in detached mode.\nfunc (c *Controller) runBackgroundCommand(ctx context.Context, cancel context.CancelFunc, request *ExecuteCodeRequest) error {\n\tsession := c.newContextID()\n\trequest.Hooks.OnExecuteInit(session)\n\n\tpipe, err := c.combinedOutputDescriptor(session)\n\tif err != nil {\n\t\tcancel()\n\t\treturn fmt.Errorf(\"failed to get combined output descriptor: %w\", err)\n\t}\n\tstdoutPath := c.combinedOutputFileName(session)\n\tstderrPath := c.combinedOutputFileName(session)\n\n\tsignals := make(chan os.Signal, 1)\n\tdefer close(signals)\n\tsignal.Notify(signals)\n\tdefer signal.Reset()\n\n\tstartAt := time.Now()\n\tlog.Info(\"received command: %v\", request.Code)\n\tshell := getShell()\n\tcmd := exec.CommandContext(ctx, shell, \"-c\", request.Code)\n\tcmd.Dir = request.Cwd\n\t// Configure credentials and process group\n\tcred, err := buildCredential(request.Uid, request.Gid)\n\tif err != nil {\n\t\tlog.Error(\"failed to build credentials: %v\", err)\n\t}\n\tcmd.SysProcAttr = &syscall.SysProcAttr{\n\t\tSetpgid: true,\n\t\tCredential: cred,\n\t}\n\n\tcmd.Stdout = pipe\n\tcmd.Stderr = pipe\n\textraEnv := mergeExtraEnvs(loadExtraEnvFromFile(), request.Envs)\n\tcmd.Env = mergeEnvs(os.Environ(), extraEnv)\n\n\t// use DevNull as stdin so interactive programs exit immediately.\n\tdevNull, err := os.Open(os.DevNull)\n\tif err == nil {\n\t\tcmd.Stdin = devNull\n\t\tdefer devNull.Close()\n\t}\n\n\terr = cmd.Start()\n\tkernel := &commandKernel{\n\t\tpid: -1,\n\t\tstdoutPath: stdoutPath,\n\t\tstderrPath: stderrPath,\n\t\tstartedAt: startAt,\n\t\trunning: true,\n\t\tcontent: request.Code,\n\t\tisBackground: true,\n\t}\n\tif err != nil {\n\t\tcancel()\n\t\tlog.Error(\"CommandExecError: error starting commands: %v\", err)\n\t\tkernel.running = false\n\t\tc.storeCommandKernel(session, kernel)\n\t\tc.markCommandFinished(session, 255, err.Error())\n\t\treturn fmt.Errorf(\"failed to start commands: %w\", err)\n\t}\n\n\tsafego.Go(func() {\n\t\tdefer pipe.Close()\n\n\t\tkernel.running = true\n\t\tkernel.pid = cmd.Process.Pid\n\t\tc.storeCommandKernel(session, kernel)\n\n\t\terr = cmd.Wait()\n\t\tcancel()\n\t\tif err != nil {\n\t\t\tlog.Error(\"CommandExecError: error running commands: %v\", err)\n\t\t\texitCode := 1\n\t\t\tvar exitError *exec.ExitError\n\t\t\tif errors.As(err, &exitError) {\n\t\t\t\texitCode = exitError.ExitCode()\n\t\t\t}\n\t\t\tc.markCommandFinished(session, exitCode, err.Error())\n\t\t\treturn\n\t\t}\n\t\tc.markCommandFinished(session, 0, \"\")\n\t})\n\n\t// ensure we kill the whole process group if the context is cancelled (e.g., timeout).\n\tsafego.Go(func() {\n\t\t<-ctx.Done()\n\t\tif cmd.Process != nil {\n\t\t\t_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) // best-effort\n\t\t}\n\t})\n\n\trequest.Hooks.OnExecuteComplete(time.Since(startAt))\n\treturn nil\n}\n" }, { "path": "components/execd/pkg/runtime/command_common.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"bufio\"\n\t\"bytes\"\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"sync\"\n\t\"time\"\n)\n\n// tailStdPipe streams appended log data until the process finishes.\nfunc (c *Controller) tailStdPipe(file string, onExecute func(text string), done <-chan struct{}) {\n\tlastPos := int64(0)\n\tticker := time.NewTicker(100 * time.Millisecond)\n\tdefer ticker.Stop()\n\n\tmutex := &sync.Mutex{}\n\tfor {\n\t\tselect {\n\t\tcase <-done:\n\t\t\tc.readFromPos(mutex, file, lastPos, onExecute, true)\n\t\t\treturn\n\t\tcase <-ticker.C:\n\t\t\tnewPos := c.readFromPos(mutex, file, lastPos, onExecute, false)\n\t\t\tlastPos = newPos\n\t\t}\n\t}\n}\n\n// getCommandKernel retrieves a command execution context.\nfunc (c *Controller) getCommandKernel(sessionID string) *commandKernel {\n\tif v, ok := c.commandClientMap.Load(sessionID); ok {\n\t\tif kernel, ok := v.(*commandKernel); ok {\n\t\t\treturn kernel\n\t\t}\n\t}\n\treturn nil\n}\n\n// storeCommandKernel registers a command execution context.\nfunc (c *Controller) storeCommandKernel(sessionID string, kernel *commandKernel) {\n\tc.commandClientMap.Store(sessionID, kernel)\n}\n\n// stdLogDescriptor creates temporary files for capturing command output.\n// It ensures the temp directory exists before opening files, so that commands\n// continue to work even after the /tmp directory has been removed and recreated.\nfunc (c *Controller) stdLogDescriptor(session string) (io.WriteCloser, io.WriteCloser, error) {\n\tlogDir := os.TempDir()\n\tif err := os.MkdirAll(logDir, 0o755); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to create temp dir %s: %w\", logDir, err)\n\t}\n\n\tstdout, err := os.OpenFile(c.stdoutFileName(session), os.O_RDWR|os.O_CREATE|os.O_TRUNC, os.ModePerm)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\tstderr, err := os.OpenFile(c.stderrFileName(session), os.O_RDWR|os.O_CREATE|os.O_TRUNC, os.ModePerm)\n\tif err != nil {\n\t\tstdout.Close()\n\t\treturn nil, nil, err\n\t}\n\n\treturn stdout, stderr, nil\n}\n\nfunc (c *Controller) combinedOutputDescriptor(session string) (io.WriteCloser, error) {\n\tlogDir := os.TempDir()\n\tif err := os.MkdirAll(logDir, 0o755); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create temp dir %s: %w\", logDir, err)\n\t}\n\treturn os.OpenFile(c.combinedOutputFileName(session), os.O_RDWR|os.O_CREATE|os.O_TRUNC, os.ModePerm)\n}\n\n// stdoutFileName constructs the stdout log path.\nfunc (c *Controller) stdoutFileName(session string) string {\n\treturn filepath.Join(os.TempDir(), session+\".stdout\")\n}\n\n// stderrFileName constructs the stderr log path.\nfunc (c *Controller) stderrFileName(session string) string {\n\treturn filepath.Join(os.TempDir(), session+\".stderr\")\n}\n\nfunc (c *Controller) combinedOutputFileName(session string) string {\n\treturn filepath.Join(os.TempDir(), session+\".output\")\n}\n\n// readFromPos streams new content from a file starting at startPos.\nfunc (c *Controller) readFromPos(mutex *sync.Mutex, filepath string, startPos int64, onExecute func(string), flushIncomplete bool) int64 {\n\tif !mutex.TryLock() {\n\t\treturn -1\n\t}\n\tdefer mutex.Unlock()\n\n\tfile, err := os.Open(filepath)\n\tif err != nil {\n\t\treturn startPos\n\t}\n\tdefer file.Close()\n\n\t_, _ = file.Seek(startPos, 0) //nolint:errcheck\n\n\treader := bufio.NewReader(file)\n\tvar buffer bytes.Buffer\n\tvar currentPos int64 = startPos\n\n\tfor {\n\t\tb, err := reader.ReadByte()\n\t\tif err != nil {\n\t\t\tif err == io.EOF {\n\t\t\t\t// If buffer has content but no newline, flush if needed, otherwise wait for next read\n\t\t\t\tif flushIncomplete && buffer.Len() > 0 {\n\t\t\t\t\tonExecute(buffer.String())\n\t\t\t\t\tbuffer.Reset()\n\t\t\t\t}\n\t\t\t}\n\t\t\tbreak\n\t\t}\n\t\tcurrentPos++\n\n\t\t// Check if it's a line terminator (\\n or \\r)\n\t\tif b == '\\n' || b == '\\r' {\n\t\t\t// If buffer has content, output this line\n\t\t\tif buffer.Len() > 0 {\n\t\t\t\tonExecute(buffer.String())\n\t\t\t\tbuffer.Reset()\n\t\t\t}\n\t\t\t// Skip line terminator\n\t\t\tcontinue\n\t\t}\n\n\t\tbuffer.WriteByte(b)\n\t}\n\n\tendPos, _ := file.Seek(0, 1)\n\t// If the last read position doesn't end with a newline, return buffer start position and wait for next flush\n\tif !flushIncomplete && buffer.Len() > 0 {\n\t\treturn currentPos - int64(buffer.Len())\n\t}\n\treturn endPos\n}\n" }, { "path": "components/execd/pkg/runtime/command_status.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\t\"time\"\n)\n\n// CommandStatus describes the lifecycle state of a command.\ntype CommandStatus struct {\n\tSession string `json:\"session\"`\n\tRunning bool `json:\"running\"`\n\tExitCode *int `json:\"exit_code,omitempty\"`\n\tError string `json:\"error,omitempty\"`\n\tStartedAt time.Time `json:\"started_at,omitempty\"`\n\tFinishedAt *time.Time `json:\"finished_at,omitempty\"`\n\tContent string `json:\"content,omitempty\"`\n}\n\n// CommandOutput contains non-streamed stdout/stderr plus status.\ntype CommandOutput struct {\n\tCommandStatus\n\tStdout string `json:\"stdout\"`\n\tStderr string `json:\"stderr\"`\n}\n\nfunc (c *Controller) commandSnapshot(session string) *commandKernel {\n\tvar kernel *commandKernel\n\tif v, ok := c.commandClientMap.Load(session); ok {\n\t\tkernel, _ = v.(*commandKernel)\n\t}\n\tif kernel == nil {\n\t\treturn nil\n\t}\n\n\tcp := *kernel\n\treturn &cp\n}\n\n// GetCommandStatus returns the execution status for a command session.\nfunc (c *Controller) GetCommandStatus(session string) (*CommandStatus, error) {\n\tkernel := c.commandSnapshot(session)\n\tif kernel == nil {\n\t\treturn nil, fmt.Errorf(\"command not found: %s\", session)\n\t}\n\n\tstatus := &CommandStatus{\n\t\tSession: session,\n\t\tRunning: kernel.running,\n\t\tExitCode: kernel.exitCode,\n\t\tError: kernel.errMsg,\n\t\tStartedAt: kernel.startedAt,\n\t\tFinishedAt: kernel.finishedAt,\n\t\tContent: kernel.content,\n\t}\n\treturn status, nil\n}\n\n// SeekBackgroundCommandOutput returns accumulated stdout/stderr and status for a session.\nfunc (c *Controller) SeekBackgroundCommandOutput(session string, cursor int64) ([]byte, int64, error) {\n\tkernel := c.commandSnapshot(session)\n\tif kernel == nil {\n\t\treturn nil, -1, fmt.Errorf(\"command not found: %s\", session)\n\t}\n\n\tif !kernel.isBackground {\n\t\treturn nil, -1, fmt.Errorf(\"command %s is not running in background\", session)\n\t}\n\n\tfile, err := os.Open(kernel.stdoutPath)\n\tif err != nil {\n\t\treturn nil, -1, fmt.Errorf(\"error open combined output file for command %s: %w\", session, err)\n\t}\n\tdefer file.Close()\n\n\t// Seek to the cursor position\n\t_, err = file.Seek(cursor, 0)\n\tif err != nil {\n\t\treturn nil, -1, fmt.Errorf(\"error seek file: %w\", err)\n\t}\n\n\t// Read all content from cursor to end\n\tdata, err := io.ReadAll(file)\n\tif err != nil {\n\t\treturn nil, -1, fmt.Errorf(\"error read file: %w\", err)\n\t}\n\n\t// Get current file position (end of file)\n\tcurrentPos, err := file.Seek(0, 1)\n\tif err != nil {\n\t\treturn nil, -1, fmt.Errorf(\"error get current position: %w\", err)\n\t}\n\n\treturn data, currentPos, nil\n}\n\n// markCommandFinished updates bookkeeping when a command exits.\nfunc (c *Controller) markCommandFinished(session string, exitCode int, errMsg string) {\n\tnow := time.Now()\n\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\tvar kernel *commandKernel\n\tif v, ok := c.commandClientMap.Load(session); ok {\n\t\tkernel, _ = v.(*commandKernel)\n\t}\n\tif kernel == nil {\n\t\treturn\n\t}\n\n\tkernel.exitCode = &exitCode\n\tkernel.errMsg = errMsg\n\tkernel.running = false\n\tkernel.finishedAt = &now\n}\n" }, { "path": "components/execd/pkg/runtime/command_status_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"strings\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestGetCommandStatus_NotFound(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\n\t_, err := c.GetCommandStatus(\"missing\")\n\trequire.Error(t, err, \"expected error for missing session\")\n}\n\nfunc TestGetCommandStatus_Running(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\n\tvar session string\n\treq := &ExecuteCodeRequest{\n\t\tLanguage: BackgroundCommand,\n\t\tCode: \"sleep 2\",\n\t\tHooks: ExecuteResultHook{\n\t\t\tOnExecuteInit: func(id string) { session = id },\n\t\t\tOnExecuteComplete: func(time.Duration) {},\n\t\t},\n\t}\n\n\tctx, cancel := context.WithCancel(context.Background())\n\trequire.NoError(t, c.runBackgroundCommand(ctx, cancel, req))\n\trequire.NotEmpty(t, session, \"session should be set by OnExecuteInit\")\n\n\t// Poll until status is registered (runBackgroundCommand stores kernel asynchronously).\n\tdeadline := time.Now().Add(5 * time.Second)\n\tvar (\n\t\tstatus *CommandStatus\n\t\terr error\n\t)\n\tfor time.Now().Before(deadline) {\n\t\tstatus, err = c.GetCommandStatus(session)\n\t\tif err == nil {\n\t\t\tbreak\n\t\t}\n\t\tif strings.Contains(err.Error(), \"not found\") {\n\t\t\ttime.Sleep(50 * time.Millisecond)\n\t\t\tcontinue\n\t\t}\n\t\trequire.NoError(t, err, \"GetCommandStatus unexpected error\")\n\t}\n\trequire.NoError(t, err, \"GetCommandStatus error after retry\")\n\n\trequire.NotNil(t, status)\n\trequire.True(t, status.Running, \"expected running=true\")\n\trequire.Nil(t, status.ExitCode, \"expected exitCode to be nil while running\")\n\trequire.Nil(t, status.FinishedAt, \"expected finishedAt to be nil while running\")\n\trequire.False(t, status.StartedAt.IsZero(), \"expected startedAt to be set\")\n\tt.Log(status)\n}\n\nfunc TestSeekBackgroundCommandOutput_Completed(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\n\ttmpDir := t.TempDir()\n\tsession := \"sess-done\"\n\tstdoutPath := filepath.Join(tmpDir, session+\".stdout\")\n\n\tstdoutContent := \"hello stdout\"\n\trequire.NoError(t, os.WriteFile(stdoutPath, []byte(stdoutContent), 0o644))\n\n\tstarted := time.Now().Add(-2 * time.Second)\n\tfinished := time.Now()\n\texitCode := 0\n\tkernel := &commandKernel{\n\t\tpid: 456,\n\t\tstdoutPath: stdoutPath,\n\t\tisBackground: true,\n\t\tstartedAt: started,\n\t\tfinishedAt: &finished,\n\t\texitCode: &exitCode,\n\t\terrMsg: \"\",\n\t\trunning: false,\n\t}\n\tc.storeCommandKernel(session, kernel)\n\n\toutput, cursor, err := c.SeekBackgroundCommandOutput(session, 0)\n\trequire.NoError(t, err, \"GetCommandOutput error\")\n\n\trequire.Greater(t, cursor, int64(0), \"expected cursor>=0\")\n\trequire.Equal(t, stdoutContent, string(output))\n}\n\nfunc TestSeekBackgroundCommandOutput_WithRunBackgroundCommand(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\n\texpected := \"line1\\nline2\\n\"\n\tvar session string\n\treq := &ExecuteCodeRequest{\n\t\tLanguage: BackgroundCommand,\n\t\tCode: \"printf 'line1\\nline2\\n'\",\n\t\tHooks: ExecuteResultHook{\n\t\t\tOnExecuteInit: func(id string) { session = id },\n\t\t\tOnExecuteComplete: func(executionTime time.Duration) {},\n\t\t\t// other hooks unused in this test\n\t\t},\n\t}\n\n\tctx, cancel := context.WithCancel(context.Background())\n\trequire.NoError(t, c.runBackgroundCommand(ctx, cancel, req))\n\trequire.NotEmpty(t, session, \"session should be set by OnExecuteInit\")\n\n\tvar (\n\t\toutput []byte\n\t\tcursor int64\n\t\terr error\n\t)\n\n\tdeadline := time.Now().Add(5 * time.Second)\n\tfor time.Now().Before(deadline) {\n\t\toutput, cursor, err = c.SeekBackgroundCommandOutput(session, 0)\n\t\tif err == nil && len(output) > 0 {\n\t\t\tbreak\n\t\t}\n\t\ttime.Sleep(100 * time.Millisecond)\n\t}\n\trequire.NoError(t, err, \"SeekBackgroundCommandOutput error\")\n\trequire.Equal(t, expected, string(output))\n\trequire.GreaterOrEqual(t, cursor, int64(len(expected)), \"cursor should advance to end of file\")\n\n\t// incremental seek from current cursor should return empty data and same-or-higher cursor\n\toutput2, cursor2, err := c.SeekBackgroundCommandOutput(session, cursor)\n\trequire.NoError(t, err, \"SeekBackgroundCommandOutput (second call) error\")\n\trequire.Empty(t, output2, \"expected no new output\")\n\trequire.GreaterOrEqual(t, cursor2, cursor, \"cursor should not move backwards\")\n}\n" }, { "path": "components/execd/pkg/runtime/command_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"os\"\n\t\"os/exec\"\n\t\"path/filepath\"\n\t\"strings\"\n\t\"sync\"\n\t\"testing\"\n\t\"time\"\n\n\tgoruntime \"runtime\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/stretchr/testify/assert\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestReadFromPos_SplitsOnCRAndLF(t *testing.T) {\n\ttmp := t.TempDir()\n\tlogFile := filepath.Join(tmp, \"stdout.log\")\n\n\tmutex := &sync.Mutex{}\n\n\tinitial := \"line1\\nprog 10%\\rprog 20%\\rprog 30%\\nlast\\n\"\n\trequire.NoError(t, os.WriteFile(logFile, []byte(initial), 0o644))\n\n\tvar got []string\n\tc := &Controller{}\n\tnextPos := c.readFromPos(mutex, logFile, 0, func(s string) { got = append(got, s) }, false)\n\n\twant := []string{\"line1\", \"prog 10%\", \"prog 20%\", \"prog 30%\", \"last\"}\n\trequire.Len(t, got, len(want))\n\tfor i := range want {\n\t\trequire.Equal(t, want[i], got[i], \"token[%d] mismatch\", i)\n\t}\n\n\t// append more content and ensure incremental read only yields the new part\n\tappendPart := \"tail1\\r\\ntail2\\n\"\n\tf, err := os.OpenFile(logFile, os.O_APPEND|os.O_WRONLY, 0o644)\n\trequire.NoError(t, err)\n\t_, err = f.WriteString(appendPart)\n\trequire.NoError(t, err, \"append write\")\n\t_ = f.Close()\n\n\tgot = got[:0]\n\tc.readFromPos(mutex, logFile, nextPos, func(s string) { got = append(got, s) }, false)\n\twant = []string{\"tail1\", \"tail2\"}\n\trequire.Len(t, got, len(want))\n\tfor i := range want {\n\t\trequire.Equal(t, want[i], got[i], \"incremental token[%d] mismatch\", i)\n\t}\n}\n\nfunc TestReadFromPos_LongLine(t *testing.T) {\n\ttmp := t.TempDir()\n\tlogFile := filepath.Join(tmp, \"stdout.log\")\n\n\t// construct a single line larger than the default 64KB, but under 5MB\n\tlongLine := strings.Repeat(\"x\", 256*1024) + \"\\n\" // 256KB\n\trequire.NoError(t, os.WriteFile(logFile, []byte(longLine), 0o644))\n\n\tvar got []string\n\tc := &Controller{}\n\tc.readFromPos(&sync.Mutex{}, logFile, 0, func(s string) { got = append(got, s) }, false)\n\n\trequire.Len(t, got, 1, \"expected one token\")\n\trequire.Equal(t, strings.TrimSuffix(longLine, \"\\n\"), got[0], \"long line mismatch\")\n}\n\nfunc TestReadFromPos_FlushesTrailingLine(t *testing.T) {\n\ttmpDir := t.TempDir()\n\tfile := filepath.Join(tmpDir, \"stdout.log\")\n\tcontent := []byte(\"line1\\nlastline-without-newline\")\n\terr := os.WriteFile(file, content, 0o644)\n\tassert.NoError(t, err)\n\n\tc := NewController(\"\", \"\")\n\tmutex := &sync.Mutex{}\n\tvar lines []string\n\tonExecute := func(text string) {\n\t\tlines = append(lines, text)\n\t}\n\n\t// First read: should only get complete lines with newlines\n\tpos := c.readFromPos(mutex, file, 0, onExecute, false)\n\tassert.GreaterOrEqual(t, pos, int64(0))\n\tassert.Equal(t, []string{\"line1\"}, lines)\n\n\t// Flush at end: should output the last line (without newline)\n\tc.readFromPos(mutex, file, pos, onExecute, true)\n\tassert.Equal(t, []string{\"line1\", \"lastline-without-newline\"}, lines)\n}\n\nfunc TestRunCommand_Echo(t *testing.T) {\n\tif goruntime.GOOS == \"windows\" {\n\t\tt.Skip(\"bash not available on windows\")\n\t}\n\tif _, err := exec.LookPath(\"bash\"); err != nil {\n\t\tt.Skip(\"bash not found in PATH\")\n\t}\n\n\tc := NewController(\"\", \"\")\n\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\tvar (\n\t\tsessionID string\n\t\tstdoutLines []string\n\t\tstderrLines []string\n\t\tcompleteCh = make(chan struct{}, 1)\n\t)\n\n\treq := &ExecuteCodeRequest{\n\t\tCode: `echo \"hello\"; echo \"errline\" 1>&2`,\n\t\tCwd: t.TempDir(),\n\t\tTimeout: 5 * time.Second,\n\t\tHooks: ExecuteResultHook{\n\t\t\tOnExecuteInit: func(s string) { sessionID = s },\n\t\t\tOnExecuteStdout: func(s string) {\n\t\t\t\tstdoutLines = append(stdoutLines, s)\n\t\t\t},\n\t\t\tOnExecuteStderr: func(s string) {\n\t\t\t\tstderrLines = append(stderrLines, s)\n\t\t\t},\n\t\t\tOnExecuteError: func(err *execute.ErrorOutput) {\n\t\t\t\trequire.Failf(t, \"unexpected error hook\", \"%+v\", err)\n\t\t\t},\n\t\t\tOnExecuteComplete: func(_ time.Duration) {\n\t\t\t\tcompleteCh <- struct{}{}\n\t\t\t},\n\t\t},\n\t}\n\n\trequire.NoError(t, c.runCommand(ctx, req))\n\n\tselect {\n\tcase <-completeCh:\n\tcase <-time.After(2 * time.Second):\n\t\trequire.Fail(t, \"timeout waiting for completion hook\")\n\t}\n\n\trequire.NotEmpty(t, sessionID, \"expected session id to be set\")\n\trequire.Equal(t, []string{\"hello\"}, stdoutLines)\n\trequire.Equal(t, []string{\"errline\"}, stderrLines)\n}\n\nfunc TestRunCommand_Error(t *testing.T) {\n\tif goruntime.GOOS == \"windows\" {\n\t\tt.Skip(\"bash not available on windows\")\n\t}\n\tif _, err := exec.LookPath(\"bash\"); err != nil {\n\t\tt.Skip(\"bash not found in PATH\")\n\t}\n\n\tc := NewController(\"\", \"\")\n\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\tvar (\n\t\tsessionID string\n\t\tgotErr *execute.ErrorOutput\n\t\tcompleteCh = make(chan struct{}, 2)\n\t\tstdoutLines []string\n\t\tstderrLines []string\n\t)\n\n\treq := &ExecuteCodeRequest{\n\t\tCode: `echo \"before\"; exit 3`,\n\t\tCwd: t.TempDir(),\n\t\tTimeout: 5 * time.Second,\n\t\tHooks: ExecuteResultHook{\n\t\t\tOnExecuteInit: func(s string) { sessionID = s },\n\t\t\tOnExecuteStdout: func(s string) { stdoutLines = append(stdoutLines, s) },\n\t\t\tOnExecuteStderr: func(s string) { stderrLines = append(stderrLines, s) },\n\t\t\tOnExecuteError: func(err *execute.ErrorOutput) {\n\t\t\t\tgotErr = err\n\t\t\t\tcompleteCh <- struct{}{}\n\t\t\t},\n\t\t\tOnExecuteComplete: func(_ time.Duration) {\n\t\t\t\tcompleteCh <- struct{}{}\n\t\t\t},\n\t\t},\n\t}\n\n\trequire.NoError(t, c.runCommand(ctx, req))\n\n\tselect {\n\tcase <-completeCh:\n\tcase <-time.After(2 * time.Second):\n\t\trequire.Fail(t, \"timeout waiting for completion hook\")\n\t}\n\n\trequire.NotEmpty(t, sessionID, \"expected session id to be set\")\n\trequire.Equal(t, []string{\"before\"}, stdoutLines)\n\trequire.Empty(t, stderrLines, \"expected no stderr\")\n\trequire.NotNil(t, gotErr, \"expected error hook to be called\")\n\trequire.Equal(t, \"CommandExecError\", gotErr.EName)\n\trequire.Equal(t, \"3\", gotErr.EValue)\n}\n\n// TestStdLogDescriptor_AutoCreatesTempDir verifies that stdLogDescriptor\n// recreates the temp directory when it has been deleted, rather than failing.\n// Regression test for https://github.com/alibaba/OpenSandbox/issues/400.\nfunc TestStdLogDescriptor_AutoCreatesTempDir(t *testing.T) {\n\tif goruntime.GOOS == \"windows\" {\n\t\tt.Skip(\"TMPDIR env var has no effect on Windows\")\n\t}\n\n\t// Point os.TempDir() at a path that does not yet exist.\n\tmissingDir := filepath.Join(t.TempDir(), \"deleted_tmp\")\n\tt.Setenv(\"TMPDIR\", missingDir)\n\n\tc := NewController(\"\", \"\")\n\tstdout, stderr, err := c.stdLogDescriptor(\"test-session\")\n\trequire.NoError(t, err)\n\tstdout.Close()\n\tstderr.Close()\n\n\t// The directory must have been created.\n\tinfo, err := os.Stat(missingDir)\n\trequire.NoError(t, err, \"expected temp dir to be created, stat error\")\n\trequire.True(t, info.IsDir(), \"expected %s to be a directory\", missingDir)\n}\n\n// TestCombinedOutputDescriptor_AutoCreatesTempDir verifies that\n// combinedOutputDescriptor also recreates the temp directory when missing.\n// Regression test for https://github.com/alibaba/OpenSandbox/issues/400.\nfunc TestCombinedOutputDescriptor_AutoCreatesTempDir(t *testing.T) {\n\tif goruntime.GOOS == \"windows\" {\n\t\tt.Skip(\"TMPDIR env var has no effect on Windows\")\n\t}\n\n\tmissingDir := filepath.Join(t.TempDir(), \"deleted_tmp\")\n\tt.Setenv(\"TMPDIR\", missingDir)\n\n\tc := NewController(\"\", \"\")\n\tf, err := c.combinedOutputDescriptor(\"test-session\")\n\trequire.NoError(t, err)\n\tf.Close()\n\n\tinfo, err := os.Stat(missingDir)\n\trequire.NoError(t, err, \"expected temp dir to be created, stat error\")\n\trequire.True(t, info.IsDir(), \"expected %s to be a directory\", missingDir)\n}\n" }, { "path": "components/execd/pkg/runtime/command_windows.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build windows\n// +build windows\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"os/exec\"\n\t\"strconv\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/util/safego\"\n)\n\n// runCommand executes shell commands and streams their output on Windows.\nfunc (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest) error {\n\tsession := c.newContextID()\n\trequest.Hooks.OnExecuteInit(session)\n\n\tstdout, stderr, err := c.stdLogDescriptor(session)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to get stdlog descriptor: %w\", err)\n\t}\n\n\tstartAt := time.Now()\n\tlog.Info(\"received command: %v\", request.Code)\n\tcmd := exec.CommandContext(ctx, \"cmd\", \"/C\", request.Code)\n\n\tcmd.Stdout = stdout\n\tcmd.Stderr = stderr\n\tcmd.Dir = request.Cwd\n\textraEnv := mergeExtraEnvs(loadExtraEnvFromFile(), request.Envs)\n\tcmd.Env = mergeEnvs(os.Environ(), extraEnv)\n\n\tdone := make(chan struct{}, 1)\n\tsafego.Go(func() {\n\t\tc.tailStdPipe(c.stdoutFileName(session), request.Hooks.OnExecuteStdout, done)\n\t})\n\tsafego.Go(func() {\n\t\tc.tailStdPipe(c.stderrFileName(session), request.Hooks.OnExecuteStderr, done)\n\t})\n\n\terr = cmd.Start()\n\tif err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"CommandExecError\", EValue: err.Error()})\n\t\tlog.Error(\"CommandExecError: error starting commands: %v\", err)\n\t\treturn nil\n\t}\n\n\tkernel := &commandKernel{\n\t\tpid: cmd.Process.Pid,\n\t\tcontent: request.Code,\n\t\tisBackground: false,\n\t}\n\tc.storeCommandKernel(session, kernel)\n\n\terr = cmd.Wait()\n\tclose(done)\n\tif err != nil {\n\t\tvar eName, eValue string\n\t\tvar traceback []string\n\n\t\tvar exitError *exec.ExitError\n\t\tif errors.As(err, &exitError) {\n\t\t\texitCode := exitError.ExitCode()\n\t\t\teName = \"CommandExecError\"\n\t\t\teValue = strconv.Itoa(exitCode)\n\t\t} else {\n\t\t\teName = \"CommandExecError\"\n\t\t\teValue = err.Error()\n\t\t}\n\t\ttraceback = []string{err.Error()}\n\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{\n\t\t\tEName: eName,\n\t\t\tEValue: eValue,\n\t\t\tTraceback: traceback,\n\t\t})\n\n\t\tlog.Error(\"CommandExecError: error running commands: %v\", err)\n\t\treturn nil\n\t}\n\trequest.Hooks.OnExecuteComplete(time.Since(startAt))\n\treturn nil\n}\n\n// runBackgroundCommand executes shell commands in detached mode on Windows.\nfunc (c *Controller) runBackgroundCommand(ctx context.Context, cancel context.CancelFunc, request *ExecuteCodeRequest) error {\n\tsession := c.newContextID()\n\trequest.Hooks.OnExecuteInit(session)\n\n\tpipe, err := c.combinedOutputDescriptor(session)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to get combined output descriptor: %w\", err)\n\t}\n\tstdoutPath := c.combinedOutputFileName(session)\n\tstderrPath := c.combinedOutputFileName(session)\n\n\tstartAt := time.Now()\n\tlog.Info(\"received command: %v\", request.Code)\n\tcmd := exec.CommandContext(ctx, \"cmd\", \"/C\", request.Code)\n\n\tcmd.Dir = request.Cwd\n\tcmd.Stdout = pipe\n\tcmd.Stderr = pipe\n\textraEnv := mergeExtraEnvs(loadExtraEnvFromFile(), request.Envs)\n\tcmd.Env = mergeEnvs(os.Environ(), extraEnv)\n\n\tdevNull, _ := os.OpenFile(os.DevNull, os.O_RDWR, 0) // best-effort, ignore error\n\tcmd.Stdin = devNull\n\n\tsafego.Go(func() {\n\t\terr := cmd.Start()\n\t\tif err != nil {\n\t\t\tlog.Error(\"CommandExecError: error starting commands: %v\", err)\n\t\t\tpipe.Close() // best-effort\n\t\t\tcancel()\n\t\t\treturn\n\t\t}\n\n\t\tkernel := &commandKernel{\n\t\t\tpid: cmd.Process.Pid,\n\t\t\tcontent: request.Code,\n\t\t\tstdoutPath: stdoutPath,\n\t\t\tstderrPath: stderrPath,\n\t\t\tstartedAt: startAt,\n\t\t\trunning: true,\n\t\t\tisBackground: true,\n\t\t}\n\t\tc.storeCommandKernel(session, kernel)\n\n\t\tsafego.Go(func() {\n\t\t\t<-ctx.Done()\n\t\t\tif cmd.Process != nil {\n\t\t\t\t_ = cmd.Process.Kill() // best-effort\n\t\t\t}\n\t\t})\n\n\t\terr = cmd.Wait()\n\t\tcancel()\n\t\tpipe.Close() // best-effort\n\t\tdevNull.Close() // best-effort\n\n\t\tif err != nil {\n\t\t\tlog.Error(\"CommandExecError: error running commands: %v\", err)\n\t\t\texitCode := 1\n\t\t\tvar exitError *exec.ExitError\n\t\t\tif errors.As(err, &exitError) {\n\t\t\t\texitCode = exitError.ExitCode()\n\t\t\t}\n\t\t\tc.markCommandFinished(session, exitCode, err.Error())\n\t\t\treturn\n\t\t}\n\t\tc.markCommandFinished(session, 0, \"\")\n\t})\n\n\trequest.Hooks.OnExecuteComplete(time.Since(startAt))\n\treturn nil\n}\n" }, { "path": "components/execd/pkg/runtime/context.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"strings\"\n\n\t\"github.com/google/uuid\"\n\t\"k8s.io/client-go/util/retry\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter\"\n\tjupytersession \"github.com/alibaba/opensandbox/execd/pkg/jupyter/session\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\n// CreateContext provisions a kernel-backed session and returns its ID.\n// Bash language uses Jupyter kernel like other languages; for pipe-based bash sessions use CreateBashSession (session API).\nfunc (c *Controller) CreateContext(req *CreateContextRequest) (string, error) {\n\t// Create a new Jupyter session.\n\tvar (\n\t\tclient *jupyter.Client\n\t\tsession *jupytersession.Session\n\t\terr error\n\t)\n\n\terr = retry.OnError(kernelWaitingBackoff, func(err error) bool {\n\t\tlog.Error(\"failed to create session, retrying: %v\", err)\n\t\treturn err != nil\n\t}, func() error {\n\t\tclient, session, err = c.createJupyterContext(*req)\n\t\treturn err\n\t})\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tkernel := &jupyterKernel{\n\t\tkernelID: session.Kernel.ID,\n\t\tclient: client,\n\t\tlanguage: req.Language,\n\t}\n\tc.storeJupyterKernel(session.ID, kernel)\n\n\terr = c.setWorkingDir(kernel, req)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to setup working dir: %w\", err)\n\t}\n\n\treturn session.ID, nil\n}\n\nfunc (c *Controller) DeleteContext(session string) error {\n\treturn c.deleteSessionAndCleanup(session)\n}\n\nfunc (c *Controller) GetContext(session string) (CodeContext, error) {\n\tkernel := c.getJupyterKernel(session)\n\tif kernel == nil {\n\t\treturn CodeContext{}, ErrContextNotFound\n\t}\n\treturn CodeContext{\n\t\tID: session,\n\t\tLanguage: kernel.language,\n\t}, nil\n}\n\nfunc (c *Controller) ListContext(language string) ([]CodeContext, error) {\n\tswitch language {\n\tcase Command.String(), BackgroundCommand.String(), SQL.String():\n\t\treturn nil, fmt.Errorf(\"unsupported language context operation: %s\", language)\n\tcase \"\":\n\t\treturn c.listAllContexts()\n\tdefault:\n\t\treturn c.listLanguageContexts(Language(language))\n\t}\n}\n\nfunc (c *Controller) DeleteLanguageContext(language Language) error {\n\tcontexts, err := c.listLanguageContexts(language)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tseen := make(map[string]struct{})\n\tfor _, context := range contexts {\n\t\tif _, ok := seen[context.ID]; ok {\n\t\t\tcontinue\n\t\t}\n\t\tseen[context.ID] = struct{}{}\n\n\t\tif err := c.deleteSessionAndCleanup(context.ID); err != nil {\n\t\t\treturn fmt.Errorf(\"error deleting context %s: %w\", context.ID, err)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (c *Controller) deleteSessionAndCleanup(session string) error {\n\tif c.getJupyterKernel(session) == nil {\n\t\treturn ErrContextNotFound\n\t}\n\tif err := c.jupyterClient().DeleteSession(session); err != nil {\n\t\treturn err\n\t}\n\tc.jupyterClientMap.Delete(session)\n\tc.deleteDefaultSessionByID(session)\n\treturn nil\n}\n\nfunc (c *Controller) newContextID() string {\n\treturn strings.ReplaceAll(uuid.New().String(), \"-\", \"\")\n}\n\nfunc (c *Controller) newIpynbPath(sessionID, cwd string) (string, error) {\n\tif cwd != \"\" {\n\t\terr := os.MkdirAll(cwd, os.ModePerm)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t}\n\n\treturn filepath.Join(cwd, fmt.Sprintf(\"%s.ipynb\", sessionID)), nil\n}\n\n// createDefaultLanguageJupyterContext prewarms a session for stateless execution.\nfunc (c *Controller) createDefaultLanguageJupyterContext(language Language) error {\n\tif c.getDefaultLanguageSession(language) != \"\" {\n\t\treturn nil\n\t}\n\n\tvar (\n\t\tclient *jupyter.Client\n\t\tsession *jupytersession.Session\n\t\terr error\n\t)\n\terr = retry.OnError(kernelWaitingBackoff, func(err error) bool {\n\t\tlog.Error(\"failed to create context, retrying: %v\", err)\n\t\treturn err != nil\n\t}, func() error {\n\t\tclient, session, err = c.createJupyterContext(CreateContextRequest{\n\t\t\tLanguage: language,\n\t\t\tCwd: \"\",\n\t\t})\n\t\treturn err\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tc.setDefaultLanguageSession(language, session.ID)\n\tc.jupyterClientMap.Store(session.ID, &jupyterKernel{\n\t\tkernelID: session.Kernel.ID,\n\t\tclient: client,\n\t\tlanguage: language,\n\t})\n\treturn nil\n}\n\n// createJupyterContext performs the actual context creation workflow.\nfunc (c *Controller) createJupyterContext(request CreateContextRequest) (*jupyter.Client, *jupytersession.Session, error) {\n\tclient := c.jupyterClient()\n\n\tkernel, err := c.searchKernel(client, request.Language)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tsessionID := c.newContextID()\n\tipynb, err := c.newIpynbPath(sessionID, request.Cwd)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tjupyterSession, err := client.CreateSession(sessionID, ipynb, kernel)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tkernels, err := client.ListKernels()\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tfound := false\n\tfor _, k := range kernels {\n\t\tif k.ID == jupyterSession.Kernel.ID {\n\t\t\tfound = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif !found {\n\t\treturn nil, nil, errors.New(\"kernel not found\")\n\t}\n\n\treturn client, jupyterSession, nil\n}\n\n// storeJupyterKernel caches a session -> kernel mapping.\nfunc (c *Controller) storeJupyterKernel(sessionID string, kernel *jupyterKernel) {\n\tc.jupyterClientMap.Store(sessionID, kernel)\n}\n\nfunc (c *Controller) jupyterClient() *jupyter.Client {\n\thttpClient := &http.Client{\n\t\tTransport: &jupyter.AuthTransport{\n\t\t\tToken: c.token,\n\t\t\tBase: http.DefaultTransport,\n\t\t},\n\t}\n\n\treturn jupyter.NewClient(c.baseURL,\n\t\tjupyter.WithToken(c.token),\n\t\tjupyter.WithHTTPClient(httpClient))\n}\n\nfunc (c *Controller) getDefaultLanguageSession(language Language) string {\n\tif v, ok := c.defaultLanguageSessions.Load(language); ok {\n\t\tif session, ok := v.(string); ok {\n\t\t\treturn session\n\t\t}\n\t}\n\treturn \"\"\n}\n\nfunc (c *Controller) setDefaultLanguageSession(language Language, sessionID string) {\n\tc.defaultLanguageSessions.Store(language, sessionID)\n}\n\nfunc (c *Controller) deleteDefaultSessionByID(sessionID string) {\n\tc.defaultLanguageSessions.Range(func(key, value any) bool {\n\t\tif s, ok := value.(string); ok && s == sessionID {\n\t\t\tc.defaultLanguageSessions.Delete(key)\n\t\t}\n\t\treturn true\n\t})\n}\n\nfunc (c *Controller) listAllContexts() ([]CodeContext, error) {\n\tcontexts := make([]CodeContext, 0)\n\tc.jupyterClientMap.Range(func(key, value any) bool {\n\t\tsession, _ := key.(string)\n\t\tif kernel, ok := value.(*jupyterKernel); ok && kernel != nil {\n\t\t\tcontexts = append(contexts, CodeContext{ID: session, Language: kernel.language})\n\t\t}\n\t\treturn true\n\t})\n\n\tc.defaultLanguageSessions.Range(func(key, value any) bool {\n\t\tlang, _ := key.(Language)\n\t\tsession, _ := value.(string)\n\t\tif session == \"\" {\n\t\t\treturn true\n\t\t}\n\t\tcontexts = append(contexts, CodeContext{ID: session, Language: lang})\n\t\treturn true\n\t})\n\n\treturn contexts, nil\n}\n\nfunc (c *Controller) listLanguageContexts(language Language) ([]CodeContext, error) {\n\tcontexts := make([]CodeContext, 0)\n\tc.jupyterClientMap.Range(func(key, value any) bool {\n\t\tsession, _ := key.(string)\n\t\tif kernel, ok := value.(*jupyterKernel); ok && kernel != nil && kernel.language == language {\n\t\t\tcontexts = append(contexts, CodeContext{ID: session, Language: language})\n\t\t}\n\t\treturn true\n\t})\n\n\tif defaultContext := c.getDefaultLanguageSession(language); defaultContext != \"\" {\n\t\tcontexts = append(contexts, CodeContext{ID: defaultContext, Language: language})\n\t}\n\n\treturn contexts, nil\n}\n" }, { "path": "components/execd/pkg/runtime/context_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"strings\"\n\t\"testing\"\n\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestListContextsAndNewIpynbPath(t *testing.T) {\n\tc := NewController(\"http://example\", \"token\")\n\tc.jupyterClientMap.Store(\"session-python\", &jupyterKernel{language: Python})\n\tc.defaultLanguageSessions.Store(Go, \"session-go-default\")\n\n\tpyContexts, err := c.listLanguageContexts(Python)\n\trequire.NoError(t, err)\n\trequire.Len(t, pyContexts, 1)\n\trequire.Equal(t, \"session-python\", pyContexts[0].ID)\n\trequire.Equal(t, Python, pyContexts[0].Language)\n\n\tallContexts, err := c.listAllContexts()\n\trequire.NoError(t, err)\n\trequire.Len(t, allContexts, 2)\n\n\ttmpDir := filepath.Join(t.TempDir(), \"nested\")\n\tpath, err := c.newIpynbPath(\"abc123\", tmpDir)\n\trequire.NoError(t, err)\n\t_, statErr := os.Stat(tmpDir)\n\trequire.NoError(t, statErr, \"expected directory to be created\")\n\texpected := filepath.Join(tmpDir, \"abc123.ipynb\")\n\trequire.Equal(t, expected, path)\n}\n\nfunc TestNewContextID_UniqueAndLength(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\tid1 := c.newContextID()\n\tid2 := c.newContextID()\n\n\trequire.NotEmpty(t, id1)\n\trequire.NotEmpty(t, id2)\n\trequire.NotEqual(t, id1, id2, \"expected unique ids\")\n\trequire.Len(t, id1, 32)\n\trequire.Len(t, id2, 32)\n}\n\nfunc TestNewIpynbPath_ErrorWhenCwdIsFile(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\ttmpFile := filepath.Join(t.TempDir(), \"file.txt\")\n\trequire.NoError(t, os.WriteFile(tmpFile, []byte(\"x\"), 0o644))\n\n\t_, err := c.newIpynbPath(\"abc\", tmpFile)\n\trequire.Error(t, err, \"expected error when cwd is a file\")\n}\n\nfunc TestListContextUnsupportedLanguage(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\t_, err := c.ListContext(Command.String())\n\trequire.Error(t, err, \"expected error for command language\")\n\t_, err = c.ListContext(BackgroundCommand.String())\n\trequire.Error(t, err, \"expected error for background-command language\")\n\t_, err = c.ListContext(SQL.String())\n\trequire.Error(t, err, \"expected error for sql language\")\n}\n\nfunc TestDeleteContext_NotFound(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\terr := c.DeleteContext(\"missing\")\n\trequire.Error(t, err, \"expected ErrContextNotFound\")\n\trequire.ErrorIs(t, err, ErrContextNotFound)\n}\n\nfunc TestGetContext_NotFound(t *testing.T) {\n\tc := NewController(\"\", \"\")\n\n\t_, err := c.GetContext(\"missing\")\n\trequire.Error(t, err, \"expected ErrContextNotFound\")\n\trequire.ErrorIs(t, err, ErrContextNotFound)\n}\n\nfunc TestDeleteContext_RemovesCacheOnSuccess(t *testing.T) {\n\tsessionID := \"sess-123\"\n\n\t// mock jupyter server that accepts DELETE\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\trequire.Equal(t, http.MethodDelete, r.Method, \"unexpected method\")\n\t\trequire.True(t, strings.HasSuffix(r.URL.Path, \"/api/sessions/\"+sessionID), \"unexpected path: %s\", r.URL.Path)\n\t\tw.WriteHeader(http.StatusNoContent)\n\t}))\n\tdefer server.Close()\n\n\tc := NewController(server.URL, \"token\")\n\tc.jupyterClientMap.Store(sessionID, &jupyterKernel{language: Python})\n\tc.defaultLanguageSessions.Store(Python, sessionID)\n\n\trequire.NoError(t, c.DeleteContext(sessionID))\n\n\trequire.Nil(t, c.getJupyterKernel(sessionID), \"expected cache to be cleared\")\n\t_, ok := c.defaultLanguageSessions.Load(Python)\n\trequire.False(t, ok, \"expected default session entry to be removed\")\n}\n\nfunc TestDeleteLanguageContext_RemovesCacheOnSuccess(t *testing.T) {\n\tlang := Python\n\tsession1 := \"sess-1\"\n\tsession2 := \"sess-2\"\n\n\t// mock jupyter server to accept two deletes\n\tdeleteCalls := make(map[string]int)\n\tserver := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\trequire.Equal(t, http.MethodDelete, r.Method, \"unexpected method\")\n\t\tif strings.Contains(r.URL.Path, session1) {\n\t\t\tdeleteCalls[session1]++\n\t\t} else if strings.Contains(r.URL.Path, session2) {\n\t\t\tdeleteCalls[session2]++\n\t\t} else {\n\t\t\trequire.Failf(t, \"unexpected path\", \"%s\", r.URL.Path)\n\t\t}\n\t\tw.WriteHeader(http.StatusNoContent)\n\t}))\n\tdefer server.Close()\n\n\tc := NewController(server.URL, \"token\")\n\tc.jupyterClientMap.Store(session1, &jupyterKernel{language: lang})\n\tc.jupyterClientMap.Store(session2, &jupyterKernel{language: lang})\n\tc.defaultLanguageSessions.Store(lang, session2)\n\n\trequire.NoError(t, c.DeleteLanguageContext(lang))\n\n\t_, ok := c.jupyterClientMap.Load(session1)\n\trequire.False(t, ok, \"expected session1 removed from cache\")\n\t_, ok = c.jupyterClientMap.Load(session2)\n\trequire.False(t, ok, \"expected session2 removed from cache\")\n\t_, ok = c.defaultLanguageSessions.Load(lang)\n\trequire.False(t, ok, \"expected default entry removed\")\n\trequire.Equal(t, 1, deleteCalls[session1])\n\trequire.Equal(t, 1, deleteCalls[session2])\n}\n" }, { "path": "components/execd/pkg/runtime/ctrl.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"fmt\"\n\t\"sync\"\n\t\"time\"\n\n\t\"k8s.io/apimachinery/pkg/util/wait\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter\"\n)\n\nvar kernelWaitingBackoff = wait.Backoff{\n\tSteps: 60,\n\tDuration: 500 * time.Millisecond,\n\tFactor: 1.5,\n\tJitter: 0.1,\n}\n\n// Controller manages code execution across runtimes.\ntype Controller struct {\n\tbaseURL string\n\ttoken string\n\tmu sync.RWMutex\n\tjupyterClientMap sync.Map // map[sessionID]*jupyterKernel\n\tdefaultLanguageSessions sync.Map // map[Language]string\n\tcommandClientMap sync.Map // map[sessionID]*commandKernel\n\tbashSessionClientMap sync.Map // map[sessionID]*bashSession\n\tdb *sql.DB\n\tdbOnce sync.Once\n}\n\ntype jupyterKernel struct {\n\tmu sync.Mutex\n\tkernelID string\n\tclient *jupyter.Client\n\tlanguage Language\n}\n\ntype commandKernel struct {\n\tpid int\n\tstdoutPath string\n\tstderrPath string\n\tstartedAt time.Time\n\tfinishedAt *time.Time\n\texitCode *int\n\terrMsg string\n\trunning bool\n\tisBackground bool\n\tcontent string\n}\n\n// NewController creates a runtime controller.\nfunc NewController(baseURL, token string) *Controller {\n\treturn &Controller{\n\t\tbaseURL: baseURL,\n\t\ttoken: token,\n\t}\n}\n\n// Execute dispatches a request to the correct backend.\nfunc (c *Controller) Execute(request *ExecuteCodeRequest) error {\n\tvar cancel context.CancelFunc\n\tvar ctx context.Context\n\tif request.Timeout > 0 {\n\t\tctx, cancel = context.WithTimeout(context.Background(), request.Timeout)\n\t} else {\n\t\tctx, cancel = context.WithCancel(context.Background())\n\t}\n\n\tswitch request.Language {\n\tcase Command:\n\t\tdefer cancel()\n\t\treturn c.runCommand(ctx, request)\n\tcase BackgroundCommand:\n\t\treturn c.runBackgroundCommand(ctx, cancel, request)\n\tcase Bash, Python, Java, JavaScript, TypeScript, Go:\n\t\tdefer cancel()\n\t\treturn c.runJupyter(ctx, request)\n\tcase SQL:\n\t\tdefer cancel()\n\t\treturn c.runSQL(ctx, request)\n\tdefault:\n\t\tdefer cancel()\n\t\treturn fmt.Errorf(\"unknown language: %s\", request.Language)\n\t}\n}\n" }, { "path": "components/execd/pkg/runtime/env.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"strings\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\n// loadExtraEnvFromFile reads key=value lines from EXECD_ENVS (if set).\n// Empty lines and lines starting with '#' are ignored.\nfunc loadExtraEnvFromFile() map[string]string {\n\tpath := os.Getenv(\"EXECD_ENVS\")\n\tif path == \"\" {\n\t\treturn nil\n\t}\n\n\tdata, err := os.ReadFile(path)\n\tif err != nil {\n\t\tlog.Warn(\"EXECD_ENVS: failed to read file %s: %v\", path, err)\n\t\treturn nil\n\t}\n\n\tenvs := make(map[string]string)\n\tlines := strings.Split(string(data), \"\\n\")\n\tfor _, line := range lines {\n\t\tline = strings.TrimSpace(line)\n\t\tif line == \"\" || strings.HasPrefix(line, \"#\") {\n\t\t\tcontinue\n\t\t}\n\t\tkv := strings.SplitN(line, \"=\", 2)\n\t\tif len(kv) != 2 {\n\t\t\tlog.Warn(\"EXECD_ENVS: skip malformed line: %s\", line)\n\t\t\tcontinue\n\t\t}\n\t\tenvs[kv[0]] = os.ExpandEnv(kv[1])\n\t}\n\n\treturn envs\n}\n\n// mergeEnvs overlays extra into base and returns a merged slice.\nfunc mergeEnvs(base []string, extra map[string]string) []string {\n\tif len(extra) == 0 {\n\t\treturn base\n\t}\n\n\tmerged := make(map[string]string, len(base)+len(extra))\n\tfor _, kv := range base {\n\t\tpair := strings.SplitN(kv, \"=\", 2)\n\t\tif len(pair) == 2 {\n\t\t\tmerged[pair[0]] = pair[1]\n\t\t}\n\t}\n\n\tfor k, v := range extra {\n\t\tmerged[k] = v\n\t}\n\n\tout := make([]string, 0, len(merged))\n\tfor k, v := range merged {\n\t\tout = append(out, fmt.Sprintf(\"%s=%s\", k, v))\n\t}\n\n\treturn out\n}\n\n// mergeExtraEnvs merges environment maps from file and request-level overrides.\nfunc mergeExtraEnvs(fromFile, fromRequest map[string]string) map[string]string {\n\tif len(fromRequest) == 0 {\n\t\treturn fromFile\n\t}\n\n\tmerged := make(map[string]string, len(fromFile)+len(fromRequest))\n\tfor k, v := range fromFile {\n\t\tmerged[k] = v\n\t}\n\tfor k, v := range fromRequest {\n\t\tmerged[k] = v\n\t}\n\n\treturn merged\n}\n" }, { "path": "components/execd/pkg/runtime/env_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"os\"\n\t\"path/filepath\"\n\t\"strings\"\n\t\"testing\"\n\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestLoadExtraEnvFromFileUnset(t *testing.T) {\n\tt.Setenv(\"EXECD_ENVS\", \"\")\n\trequire.Nil(t, loadExtraEnvFromFile(), \"expected nil when EXECD_ENVS unset\")\n}\n\nfunc TestLoadExtraEnvFromFileParsesAndExpands(t *testing.T) {\n\tdir := t.TempDir()\n\tenvFile := filepath.Join(dir, \"env\")\n\n\tt.Setenv(\"EXECD_ENVS\", envFile)\n\tt.Setenv(\"BASE_DIR\", \"/opt/base\")\n\n\tcontent := strings.Join([]string{\n\t\t\"# comment\",\n\t\t\"FOO=bar\",\n\t\t\"PATH=$BASE_DIR/bin\",\n\t\t\"MALFORMED\",\n\t\t\"EMPTY=\",\n\t\t\"\",\n\t}, \"\\n\")\n\n\trequire.NoError(t, os.WriteFile(envFile, []byte(content), 0o644))\n\n\tgot := loadExtraEnvFromFile()\n\trequire.Len(t, got, 3)\n\trequire.Equal(t, \"bar\", got[\"FOO\"])\n\trequire.Equal(t, \"/opt/base/bin\", got[\"PATH\"])\n\tval, ok := got[\"EMPTY\"]\n\trequire.True(t, ok)\n\trequire.Equal(t, \"\", val)\n}\n\nfunc TestLoadExtraEnvFromFileMissingFile(t *testing.T) {\n\tdir := t.TempDir()\n\tenvFile := filepath.Join(dir, \"does-not-exist\")\n\tt.Setenv(\"EXECD_ENVS\", envFile)\n\n\trequire.Nil(t, loadExtraEnvFromFile(), \"expected nil for missing file\")\n}\n\nfunc TestMergeEnvsOverlaysExtra(t *testing.T) {\n\tbase := []string{\"A=1\", \"B=2\"}\n\textra := map[string]string{\"B\": \"override\", \"C\": \"3\"}\n\n\tmerged := mergeEnvs(base, extra)\n\tgot := make(map[string]string)\n\tfor _, kv := range merged {\n\t\tparts := strings.SplitN(kv, \"=\", 2)\n\t\tif len(parts) == 2 {\n\t\t\tgot[parts[0]] = parts[1]\n\t\t}\n\t}\n\n\trequire.Len(t, got, 3)\n\trequire.Equal(t, \"1\", got[\"A\"])\n\trequire.Equal(t, \"override\", got[\"B\"])\n\trequire.Equal(t, \"3\", got[\"C\"])\n}\n\nfunc TestMergeExtraEnvsMergesAndOverrides(t *testing.T) {\n\tfromFile := map[string]string{\"A\": \"1\", \"B\": \"2\"}\n\tfromRequest := map[string]string{\"B\": \"override\", \"C\": \"3\"}\n\n\tgot := mergeExtraEnvs(fromFile, fromRequest)\n\n\trequire.Len(t, got, 3)\n\trequire.Equal(t, \"1\", got[\"A\"])\n\trequire.Equal(t, \"override\", got[\"B\"])\n\trequire.Equal(t, \"3\", got[\"C\"])\n}\n\nfunc TestMergeExtraEnvsHandlesNilFromFile(t *testing.T) {\n\tfromRequest := map[string]string{\"ONLY\": \"request\"}\n\n\tgot := mergeExtraEnvs(nil, fromRequest)\n\n\trequire.Len(t, got, 1)\n\trequire.Equal(t, \"request\", got[\"ONLY\"])\n}\n" }, { "path": "components/execd/pkg/runtime/errors.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport \"errors\"\n\nvar ErrContextNotFound = errors.New(\"context not found\")\n" }, { "path": "components/execd/pkg/runtime/helpers_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"database/sql/driver\"\n\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"sync/atomic\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/stretchr/testify/require\"\n)\n\ntype stubDriver struct {\n\tcolumns []string\n\trows [][]driver.Value\n\texecRowsAffected int64\n\tqueryErr error\n\texecErr error\n\tpingErr error\n\texecCalled int32\n\tqueryCalled int32\n}\n\ntype stubConn struct {\n\td *stubDriver\n}\n\nfunc (c *stubConn) Prepare(string) (driver.Stmt, error) { return nil, errors.New(\"not implemented\") }\nfunc (c *stubConn) Close() error { return nil }\nfunc (c *stubConn) Begin() (driver.Tx, error) { return nil, errors.New(\"not implemented\") }\n\nfunc (c *stubConn) Ping(context.Context) error {\n\treturn c.d.pingErr\n}\n\nfunc (c *stubConn) ExecContext(_ context.Context, _ string, _ []driver.NamedValue) (driver.Result, error) {\n\tatomic.AddInt32(&c.d.execCalled, 1)\n\tif c.d.execErr != nil {\n\t\treturn nil, c.d.execErr\n\t}\n\treturn driver.RowsAffected(c.d.execRowsAffected), nil\n}\n\nfunc (c *stubConn) QueryContext(_ context.Context, _ string, _ []driver.NamedValue) (driver.Rows, error) {\n\tatomic.AddInt32(&c.d.queryCalled, 1)\n\tif c.d.queryErr != nil {\n\t\treturn nil, c.d.queryErr\n\t}\n\treturn &stubRows{\n\t\tcolumns: c.d.columns,\n\t\trows: c.d.rows,\n\t}, nil\n}\n\ntype stubRows struct {\n\tcolumns []string\n\trows [][]driver.Value\n\tidx int\n}\n\nfunc (r *stubRows) Columns() []string { return r.columns }\nfunc (r *stubRows) Close() error { return nil }\nfunc (r *stubRows) Next(dest []driver.Value) error {\n\tif r.idx >= len(r.rows) {\n\t\treturn io.EOF\n\t}\n\trow := r.rows[r.idx]\n\tr.idx++\n\tfor i, v := range row {\n\t\tdest[i] = v\n\t}\n\treturn nil\n}\n\ntype stubConnector struct {\n\td *stubDriver\n}\n\nfunc (c *stubConnector) Connect(context.Context) (driver.Conn, error) {\n\treturn &stubConn{d: c.d}, nil\n}\n\nfunc (c *stubConnector) Driver() driver.Driver {\n\treturn c\n}\n\nfunc (c *stubConnector) Open(string) (driver.Conn, error) {\n\treturn &stubConn{d: c.d}, nil\n}\n\nfunc newStubDB(t *testing.T, d *stubDriver) *sql.DB {\n\tt.Helper()\n\tdriverName := fmt.Sprintf(\"stub-%d\", time.Now().UnixNano())\n\tsql.Register(driverName, &stubConnector{d: d})\n\tdb, err := sql.Open(driverName, \"\")\n\trequire.NoError(t, err)\n\treturn db\n}\n" }, { "path": "components/execd/pkg/runtime/interrupt.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build !windows\n// +build !windows\n\npackage runtime\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"strings\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\n// Interrupt stops execution in the specified session.\nfunc (c *Controller) Interrupt(sessionID string) error {\n\tswitch {\n\tcase c.getJupyterKernel(sessionID) != nil:\n\t\tkernel := c.getJupyterKernel(sessionID)\n\t\tlog.Warning(\"Interrupting Jupyter kernel %s\", kernel.kernelID)\n\t\treturn kernel.client.InterruptKernel(kernel.kernelID)\n\tcase c.getCommandKernel(sessionID) != nil:\n\t\tkernel := c.getCommandKernel(sessionID)\n\t\treturn c.killPid(kernel.pid)\n\tcase c.getBashSession(sessionID) != nil:\n\t\treturn c.closeBashSession(sessionID)\n\tdefault:\n\t\treturn errors.New(\"no such session\")\n\t}\n}\n\n// killPid sends SIGTERM followed by SIGKILL if needed.\nfunc (c *Controller) killPid(pid int) error {\n\tprocess, err := os.FindProcess(pid)\n\tif err != nil {\n\t\treturn err\n\t}\n\tlog.Warning(\"Attempting to terminate process %d\", pid)\n\n\tif err := process.Signal(syscall.SIGTERM); err != nil {\n\t\tif strings.Contains(err.Error(), \"already finished\") {\n\t\t\treturn nil\n\t\t}\n\t\tlog.Warning(\"SIGTERM failed for pid %d: %v, trying SIGKILL\", pid, err)\n\t} else {\n\t\tdone := make(chan error, 1)\n\t\tgo func() {\n\t\t\t_, err := process.Wait()\n\t\t\tdone <- err\n\t\t}()\n\n\t\tselect {\n\t\tcase err := <-done:\n\t\t\tif err == nil {\n\t\t\t\tlog.Info(\"Process %d terminated gracefully\", pid)\n\t\t\t\treturn nil\n\t\t\t}\n\t\tcase <-time.After(3 * time.Second):\n\t\t\tlog.Warning(\"Process %d did not terminate after SIGTERM, using SIGKILL\", pid)\n\t\t}\n\t}\n\n\tif err := process.Signal(syscall.SIGKILL); err != nil {\n\t\tif strings.Contains(err.Error(), \"already finished\") {\n\t\t\treturn nil\n\t\t}\n\t\treturn fmt.Errorf(\"failed to kill process %d: %w\", pid, err)\n\t}\n\n\tfor range 3 {\n\t\tif err := process.Signal(syscall.Signal(0)); err != nil {\n\t\t\tif strings.Contains(err.Error(), \"already finished\") ||\n\t\t\t\tstrings.Contains(err.Error(), \"no such process\") {\n\t\t\t\tlog.Info(\"Process %d confirmed terminated\", pid)\n\t\t\t\treturn nil\n\t\t\t}\n\t\t}\n\t\ttime.Sleep(50 * time.Millisecond)\n\t}\n\n\treturn fmt.Errorf(\"process %d might still be running\", pid)\n}\n" }, { "path": "components/execd/pkg/runtime/interrupt_windows.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build windows\n// +build windows\n\npackage runtime\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\n// Interrupt stops execution in the specified session.\nfunc (c *Controller) Interrupt(sessionID string) error {\n\tswitch {\n\tcase c.getJupyterKernel(sessionID) != nil:\n\t\tkernel := c.getJupyterKernel(sessionID)\n\t\tlog.Warning(\"Interrupting Jupyter kernel %s\", kernel.kernelID)\n\t\treturn kernel.client.InterruptKernel(kernel.kernelID)\n\tcase c.getCommandKernel(sessionID) != nil:\n\t\tkernel := c.getCommandKernel(sessionID)\n\t\treturn c.killPid(kernel.pid)\n\tdefault:\n\t\treturn errors.New(\"no such session\")\n\t}\n}\n\n// killPid terminates a process on Windows.\nfunc (c *Controller) killPid(pid int) error {\n\tprocess, err := os.FindProcess(pid)\n\tif err != nil {\n\t\treturn err\n\t}\n\tlog.Warning(\"Attempting to terminate process %d\", pid)\n\n\tif err := process.Kill(); err != nil {\n\t\treturn fmt.Errorf(\"failed to kill process %d: %w\", pid, err)\n\t}\n\n\t// Best-effort wait to reduce zombies; os.Process.Wait only works for child processes.\n\tdone := make(chan error, 1)\n\tgo func() {\n\t\t_, err := process.Wait()\n\t\tdone <- err\n\t}()\n\n\tselect {\n\tcase <-done:\n\tcase <-time.After(3 * time.Second):\n\t\tlog.Warning(\"Process %d kill wait timed out\", pid)\n\t}\n\n\treturn nil\n}\n" }, { "path": "components/execd/pkg/runtime/jupyter.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"errors\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\n// runJupyter executes code through a Jupyter kernel.\nfunc (c *Controller) runJupyter(ctx context.Context, request *ExecuteCodeRequest) error {\n\tif c.baseURL == \"\" || c.token == \"\" {\n\t\treturn errors.New(\"language runtime server not configured, please check your image runtime\")\n\t}\n\tif request.Context == \"\" {\n\t\tif c.getDefaultLanguageSession(request.Language) == \"\" {\n\t\t\tif err := c.createDefaultLanguageJupyterContext(request.Language); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t}\n\n\tvar targetSessionID string\n\tif request.Context == \"\" {\n\t\ttargetSessionID = c.getDefaultLanguageSession(request.Language)\n\t} else {\n\t\ttargetSessionID = request.Context\n\t}\n\n\tkernel := c.getJupyterKernel(targetSessionID)\n\tif kernel == nil {\n\t\treturn ErrContextNotFound\n\t}\n\n\trequest.SetDefaultHooks()\n\trequest.Hooks.OnExecuteInit(targetSessionID)\n\n\treturn c.runJupyterCode(ctx, kernel, request)\n}\n\n// runJupyterCode streams execution results for a single kernel.\n//\n//nolint:gocognit // complex due to hook handling; refactor later\nfunc (c *Controller) runJupyterCode(ctx context.Context, kernel *jupyterKernel, request *ExecuteCodeRequest) error {\n\tif !kernel.mu.TryLock() {\n\t\treturn errors.New(\"session is busy\")\n\t}\n\tdefer kernel.mu.Unlock()\n\n\terr := kernel.client.ConnectToKernel(kernel.kernelID)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer kernel.client.DisconnectFromKernel(kernel.kernelID)\n\n\tresults := make(chan *execute.ExecutionResult, 10)\n\n\terr = kernel.client.ExecuteCodeStream(kernel.kernelID, request.Code, results)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tfor {\n\t\tselect {\n\t\tcase result := <-results:\n\t\t\tif result == nil {\n\t\t\t\treturn nil\n\t\t\t}\n\n\t\t\tif result.ExecutionCount > 0 || len(result.ExecutionData) > 0 {\n\t\t\t\trequest.Hooks.OnExecuteResult(result.ExecutionData, result.ExecutionCount)\n\t\t\t}\n\n\t\t\tif result.Status != \"\" {\n\t\t\t\trequest.Hooks.OnExecuteStatus(result.Status)\n\t\t\t}\n\n\t\t\tif result.ExecutionTime > 0 {\n\t\t\t\trequest.Hooks.OnExecuteComplete(result.ExecutionTime)\n\t\t\t}\n\n\t\t\tif result.Error != nil {\n\t\t\t\trequest.Hooks.OnExecuteError(result.Error)\n\t\t\t}\n\n\t\t\tif len(result.Stream) > 0 {\n\t\t\t\tfor _, stream := range result.Stream {\n\t\t\t\t\tswitch stream.Name {\n\t\t\t\t\tcase execute.StreamStdout:\n\t\t\t\t\t\trequest.Hooks.OnExecuteStdout(stream.Text)\n\t\t\t\t\tcase execute.StreamStderr:\n\t\t\t\t\t\trequest.Hooks.OnExecuteStderr(stream.Text)\n\t\t\t\t\tdefault:\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\tcase <-ctx.Done():\n\t\t\tlog.Warning(\"context cancelled, try to interrupt kernel\")\n\t\t\terr = kernel.client.InterruptKernel(kernel.kernelID)\n\t\t\tif err != nil {\n\t\t\t\tlog.Error(\"interrupt kernel failed: %v\", err)\n\t\t\t}\n\n\t\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{\n\t\t\t\tEName: \"ContextCancelled\",\n\t\t\t\tEValue: \"Interrupt kernel\",\n\t\t\t})\n\t\t\treturn errors.New(\"context cancelled, interrupt kernel\")\n\t\t}\n\t}\n}\n\n// setWorkingDir configures the working directory for a kernel session.\nfunc (c *Controller) setWorkingDir(_ *jupyterKernel, _ *CreateContextRequest) error {\n\treturn nil\n}\n\n// getJupyterKernel retrieves a kernel connection from the session map.\nfunc (c *Controller) getJupyterKernel(sessionID string) *jupyterKernel {\n\tif v, ok := c.jupyterClientMap.Load(sessionID); ok {\n\t\tif kernel, ok := v.(*jupyterKernel); ok {\n\t\t\treturn kernel\n\t\t}\n\t}\n\treturn nil\n}\n\n// searchKernel finds a kernel spec name for the given language.\nfunc (c *Controller) searchKernel(client *jupyter.Client, language Language) (string, error) {\n\tspecs, err := client.GetKernelSpecs()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tif len(specs.Kernelspecs) == 0 {\n\t\treturn \"\", errors.New(\"no kernel specs found\")\n\t}\n\n\tvar kernelName string\n\tfor name, spec := range specs.Kernelspecs {\n\t\tif name == \"python3\" {\n\t\t\tcontinue\n\t\t}\n\n\t\tif spec.Spec.Language == language.String() {\n\t\t\tkernelName = name\n\t\t}\n\t}\n\tif kernelName == \"\" {\n\t\treturn \"\", errors.New(\"no kernel specs found\")\n\t}\n\n\treturn kernelName, nil\n}\n" }, { "path": "components/execd/pkg/runtime/language.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\n// Language represents the programming language or execution mode\ntype Language string\n\nconst (\n\tCommand Language = \"command\"\n\tBash Language = \"bash\"\n\tPython Language = \"python\"\n\tJava Language = \"java\"\n\tJavaScript Language = \"javascript\"\n\tTypeScript Language = \"typescript\"\n\tGo Language = \"go\"\n\tSQL Language = \"sql\"\n\tBackgroundCommand Language = \"background-command\"\n)\n\n// String returns the string representation of the language\nfunc (l Language) String() string {\n\treturn string(l)\n}\n" }, { "path": "components/execd/pkg/runtime/sql.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"encoding/json\"\n\t\"errors\"\n\t\"fmt\"\n\t\"strings\"\n\t\"time\"\n\n\t\"github.com/google/uuid\"\n\n\t_ \"github.com/go-sql-driver/mysql\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\n// QueryResult represents a SQL query response.\ntype QueryResult struct {\n\tColumns []string `json:\"columns,omitempty\"`\n\tRows [][]any `json:\"rows,omitempty\"`\n\tError string `json:\"error,omitempty\"`\n}\n\n// runSQL executes SQL queries based on their type.\nfunc (c *Controller) runSQL(ctx context.Context, request *ExecuteCodeRequest) error {\n\trequest.Hooks.OnExecuteInit(uuid.New().String())\n\terr := c.initDB()\n\tif err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"DBInitError\", EValue: err.Error()})\n\t\tlog.Error(\"DBInitError: error initializing db server: %v\", err)\n\t\treturn err\n\t}\n\n\terr = c.db.PingContext(ctx)\n\tif err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"DBPingError\", EValue: err.Error()})\n\t\tlog.Error(\"DBPingError: error pinging db server: %v\", err)\n\t\treturn err\n\t}\n\n\tswitch c.getQueryType(request.Code) {\n\tcase \"SELECT\":\n\t\treturn c.executeSelectSQLQuery(ctx, request)\n\tdefault:\n\t\treturn c.executeUpdateSQLQuery(ctx, request)\n\t}\n}\n\n// executeSelectSQLQuery handles SELECT statements.\nfunc (c *Controller) executeSelectSQLQuery(ctx context.Context, request *ExecuteCodeRequest) error {\n\tstartAt := time.Now()\n\n\trows, err := c.db.QueryContext(ctx, request.Code)\n\tif err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"DBQueryError\", EValue: err.Error()})\n\t\treturn nil\n\t}\n\tdefer rows.Close()\n\n\tcolumns, err := rows.Columns()\n\tif err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"DBQueryError\", EValue: err.Error()})\n\t\treturn nil\n\t}\n\n\tvar result [][]any\n\tvalues := make([]any, len(columns))\n\tscanArgs := make([]any, len(columns))\n\tfor i := range values {\n\t\tscanArgs[i] = &values[i]\n\t}\n\n\tfor rows.Next() {\n\t\terr := rows.Scan(scanArgs...)\n\t\tif err != nil {\n\t\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"RowScanError\", EValue: err.Error()})\n\t\t\treturn nil\n\t\t}\n\t\trow := make([]any, len(columns))\n\t\tfor i, v := range values {\n\t\t\tif v == nil {\n\t\t\t\trow[i] = nil\n\t\t\t} else {\n\t\t\t\trow[i] = fmt.Sprintf(\"%v\", v)\n\t\t\t}\n\t\t}\n\t\tresult = append(result, row)\n\t}\n\tif err := rows.Err(); err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"RowIterationError\", EValue: err.Error()})\n\t\treturn nil\n\t}\n\n\tqueryResult := QueryResult{\n\t\tColumns: columns,\n\t\tRows: result,\n\t}\n\tbytes, err := json.Marshal(queryResult)\n\tif err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"JSONMarshalError\", EValue: err.Error()})\n\t\treturn nil\n\t}\n\trequest.Hooks.OnExecuteResult(\n\t\tmap[string]any{\n\t\t\t\"text/plain\": string(bytes),\n\t\t},\n\t\t1,\n\t)\n\trequest.Hooks.OnExecuteComplete(time.Since(startAt))\n\treturn nil\n}\n\n// executeUpdateSQLQuery handles non-SELECT statements.\nfunc (c *Controller) executeUpdateSQLQuery(ctx context.Context, request *ExecuteCodeRequest) error {\n\tstartAt := time.Now()\n\n\tresult, err := c.db.ExecContext(ctx, request.Code)\n\tif err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"DBExecError\", EValue: err.Error()})\n\t\treturn err\n\t}\n\n\taffected, _ := result.RowsAffected()\n\tqueryResult := QueryResult{\n\t\tRows: [][]any{{affected}},\n\t\tColumns: []string{\"affected_rows\"},\n\t}\n\tbytes, err := json.Marshal(queryResult)\n\tif err != nil {\n\t\trequest.Hooks.OnExecuteError(&execute.ErrorOutput{EName: \"JSONMarshalError\", EValue: err.Error()})\n\t\treturn err\n\t}\n\trequest.Hooks.OnExecuteResult(\n\t\tmap[string]any{\n\t\t\t\"text/plain\": string(bytes),\n\t\t},\n\t\t1,\n\t)\n\trequest.Hooks.OnExecuteComplete(time.Since(startAt))\n\treturn nil\n}\n\n// getQueryType extracts the first token to decide which executor to use.\nfunc (c *Controller) getQueryType(query string) string {\n\tfields := strings.Fields(query)\n\tif len(fields) == 0 {\n\t\treturn \"\"\n\t}\n\treturn strings.ToUpper(fields[0])\n}\n\n// initDB lazily opens the local sandbox database.\nfunc (c *Controller) initDB() error {\n\tvar initErr error\n\tc.dbOnce.Do(func() {\n\t\tdsn := \"root:@tcp(127.0.0.1:3306)/\"\n\t\tdb, err := sql.Open(\"mysql\", dsn)\n\t\tif err != nil {\n\t\t\tinitErr = err\n\t\t\treturn\n\t\t}\n\n\t\terr = db.Ping()\n\t\tif err != nil {\n\t\t\tinitErr = err\n\t\t\treturn\n\t\t}\n\n\t\t_, err = db.Exec(\"CREATE DATABASE IF NOT EXISTS sandbox\")\n\t\tif err != nil {\n\t\t\tinitErr = err\n\t\t\treturn\n\t\t}\n\n\t\t_, err = db.Exec(\"USE sandbox\")\n\t\tif err != nil {\n\t\t\tinitErr = err\n\t\t\treturn\n\t\t}\n\n\t\tc.db = db\n\t})\n\n\tif initErr != nil {\n\t\treturn initErr\n\t}\n\tif c.db == nil {\n\t\treturn errors.New(\"db is not initialized\")\n\t}\n\treturn nil\n}\n" }, { "path": "components/execd/pkg/runtime/sql_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"context\"\n\t\"database/sql/driver\"\n\t\"encoding/json\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestExecuteSelectSQLQuery_Success(t *testing.T) {\n\tdriver := &stubDriver{\n\t\tcolumns: []string{\"id\", \"name\"},\n\t\trows: [][]driver.Value{\n\t\t\t{int64(1), \"alice\"},\n\t\t\t{int64(2), \"bob\"},\n\t\t},\n\t}\n\tdb := newStubDB(t, driver)\n\n\tc := NewController(\"\", \"\")\n\tc.db = db\n\n\tvar (\n\t\tgotResult map[string]any\n\t\tgotError *execute.ErrorOutput\n\t\tcompleted bool\n\t)\n\n\treq := &ExecuteCodeRequest{\n\t\tCode: \"SELECT * FROM users\",\n\t\tHooks: ExecuteResultHook{\n\t\t\tOnExecuteResult: func(result map[string]any, _ int) {\n\t\t\t\tgotResult = result\n\t\t\t},\n\t\t\tOnExecuteError: func(err *execute.ErrorOutput) {\n\t\t\t\tgotError = err\n\t\t\t},\n\t\t\tOnExecuteComplete: func(time.Duration) {\n\t\t\t\tcompleted = true\n\t\t\t},\n\t\t},\n\t}\n\n\trequire.NoError(t, c.executeSelectSQLQuery(context.Background(), req))\n\n\trequire.Nil(t, gotError, \"unexpected error hook\")\n\trequire.True(t, completed, \"expected completion hook to be triggered\")\n\n\traw, ok := gotResult[\"text/plain\"]\n\trequire.True(t, ok, \"expected text/plain payload\")\n\tvar qr QueryResult\n\trequire.NoError(t, json.Unmarshal([]byte(raw.(string)), &qr))\n\n\trequire.Equal(t, []string{\"id\", \"name\"}, qr.Columns, \"unexpected columns\")\n\trequire.Len(t, qr.Rows, 2, \"unexpected rows\")\n\trequire.Equal(t, \"1\", qr.Rows[0][0])\n\trequire.Equal(t, \"bob\", qr.Rows[1][1])\n}\n\nfunc TestExecuteUpdateSQLQuery_Success(t *testing.T) {\n\tdriver := &stubDriver{\n\t\texecRowsAffected: 3,\n\t}\n\tdb := newStubDB(t, driver)\n\n\tc := NewController(\"\", \"\")\n\tc.db = db\n\n\tvar (\n\t\tgotResult map[string]any\n\t\tgotError *execute.ErrorOutput\n\t\tcompleted bool\n\t)\n\n\treq := &ExecuteCodeRequest{\n\t\tCode: \"UPDATE users SET name='alice' WHERE id=1\",\n\t\tHooks: ExecuteResultHook{\n\t\t\tOnExecuteResult: func(result map[string]any, _ int) {\n\t\t\t\tgotResult = result\n\t\t\t},\n\t\t\tOnExecuteError: func(err *execute.ErrorOutput) {\n\t\t\t\tgotError = err\n\t\t\t},\n\t\t\tOnExecuteComplete: func(time.Duration) {\n\t\t\t\tcompleted = true\n\t\t\t},\n\t\t},\n\t}\n\n\trequire.NoError(t, c.executeUpdateSQLQuery(context.Background(), req))\n\n\trequire.Nil(t, gotError, \"unexpected error hook\")\n\trequire.True(t, completed, \"expected completion hook to be triggered\")\n\n\traw, ok := gotResult[\"text/plain\"]\n\trequire.True(t, ok, \"expected text/plain payload\")\n\tvar qr QueryResult\n\trequire.NoError(t, json.Unmarshal([]byte(raw.(string)), &qr))\n\n\trequire.Equal(t, []string{\"affected_rows\"}, qr.Columns, \"unexpected columns\")\n\trequire.Len(t, qr.Rows, 1, \"unexpected rows length\")\n\trequire.Len(t, qr.Rows[0], 1, \"unexpected row entry length\")\n\trequire.Equal(t, float64(3), qr.Rows[0][0])\n}\n" }, { "path": "components/execd/pkg/runtime/types.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"fmt\"\n\t\"sync\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n)\n\n// ExecuteResultHook groups execution callbacks.\ntype ExecuteResultHook struct {\n\tOnExecuteInit func(context string)\n\tOnExecuteResult func(result map[string]any, count int)\n\tOnExecuteStatus func(status string)\n\tOnExecuteStdout func(stdout string) //nolint:predeclared\n\tOnExecuteStderr func(stderr string) //nolint:predeclared\n\tOnExecuteError func(err *execute.ErrorOutput)\n\tOnExecuteComplete func(executionTime time.Duration)\n}\n\n// ExecuteCodeRequest represents a code execution request with context and hooks.\ntype ExecuteCodeRequest struct {\n\tLanguage Language `json:\"language\"`\n\tCode string `json:\"code\"`\n\tContext string `json:\"context\"`\n\tTimeout time.Duration `json:\"timeout\"`\n\tCwd string `json:\"cwd\"`\n\tEnvs map[string]string `json:\"envs\"`\n\tUid *uint32 `json:\"uid,omitempty\"`\n\tGid *uint32 `json:\"gid,omitempty\"`\n\tHooks ExecuteResultHook\n}\n\n// SetDefaultHooks installs stdout logging fallbacks for unset hooks.\nfunc (req *ExecuteCodeRequest) SetDefaultHooks() {\n\tif req.Hooks.OnExecuteResult == nil {\n\t\treq.Hooks.OnExecuteResult = func(result map[string]any, count int) { fmt.Printf(\"OnExecuteResult: %d, %++v\\n\", count, result) }\n\t}\n\tif req.Hooks.OnExecuteStatus == nil {\n\t\treq.Hooks.OnExecuteStatus = func(status string) { fmt.Printf(\"OnExecuteStatus: %s\\n\", status) }\n\t}\n\tif req.Hooks.OnExecuteStdout == nil {\n\t\treq.Hooks.OnExecuteStdout = func(stdout string) { fmt.Printf(\"OnExecuteStdout: %s\\n\", stdout) }\n\t}\n\tif req.Hooks.OnExecuteStderr == nil {\n\t\treq.Hooks.OnExecuteStderr = func(stderr string) { fmt.Printf(\"OnExecuteStderr: %s\\n\", stderr) }\n\t}\n\tif req.Hooks.OnExecuteError == nil {\n\t\treq.Hooks.OnExecuteError = func(err *execute.ErrorOutput) { fmt.Printf(\"OnExecuteError: %++v\\n\", err) }\n\t}\n\tif req.Hooks.OnExecuteComplete == nil {\n\t\treq.Hooks.OnExecuteComplete = func(executionTime time.Duration) {\n\t\t\tfmt.Printf(\"OnExecuteComplete: %v\\n\", executionTime)\n\t\t}\n\t}\n\tif req.Hooks.OnExecuteInit == nil {\n\t\treq.Hooks.OnExecuteInit = func(session string) { fmt.Printf(\"OnExecuteInit: %s\\n\", session) }\n\t}\n}\n\n// CreateContextRequest represents a stateful session creation request.\ntype CreateContextRequest struct {\n\tLanguage Language `json:\"language\"`\n\tCwd string `json:\"cwd\"`\n}\n\ntype CodeContext struct {\n\tID string `json:\"id,omitempty\"`\n\tLanguage Language `json:\"language\"`\n}\n\n// bashSessionConfig holds bash session configuration.\ntype bashSessionConfig struct {\n\t// StartupSource is a list of scripts sourced on startup.\n\tStartupSource []string\n\t// Session is the session identifier.\n\tSession string\n\t// StartupTimeout is the startup timeout.\n\tStartupTimeout time.Duration\n\t// Cwd is the working directory.\n\tCwd string\n}\n\n// bashSession represents a bash session.\ntype bashSession struct {\n\tconfig *bashSessionConfig\n\tmu sync.Mutex\n\tstarted bool\n\tenv map[string]string\n\tcwd string\n\n\t// currentProcessPid is the pid of the active run's process group leader (bash).\n\t// Set after cmd.Start(), cleared when run() returns. Used by close() to kill the process group.\n\tcurrentProcessPid int\n}\n" }, { "path": "components/execd/pkg/runtime/types_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage runtime\n\nimport (\n\t\"reflect\"\n\t\"testing\"\n\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestExecuteCodeRequest_SetDefaultHooks(t *testing.T) {\n\tcustomResult := func(map[string]any, int) {}\n\n\treq := &ExecuteCodeRequest{\n\t\tHooks: ExecuteResultHook{\n\t\t\tOnExecuteResult: customResult,\n\t\t},\n\t}\n\n\treq.SetDefaultHooks()\n\n\trequire.NotNil(t, req.Hooks.OnExecuteStdout)\n\trequire.NotNil(t, req.Hooks.OnExecuteStderr)\n\trequire.NotNil(t, req.Hooks.OnExecuteError)\n\trequire.NotNil(t, req.Hooks.OnExecuteResult, \"expected OnExecuteResult to remain set\")\n\trequire.Equal(t, reflect.ValueOf(customResult).Pointer(), reflect.ValueOf(req.Hooks.OnExecuteResult).Pointer(),\n\t\t\"default hooks should not override existing ones\")\n}\n" }, { "path": "components/execd/pkg/util/glob/index.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage glob\n\nfunc findUnescapedByteIndex(s string, c byte, allowEscaping bool) int {\n\tl := len(s)\n\tfor i := 0; i < l; i++ {\n\t\tif allowEscaping && s[i] == '\\\\' {\n\t\t\t// skip next byte\n\t\t\ti++\n\t\t} else if s[i] == c {\n\t\t\treturn i\n\t\t}\n\t}\n\treturn -1\n}\n\n// findMatchedClosingAltIndex finds the matching `}` for a `{`.\nfunc findMatchedClosingAltIndex(s string, allowEscaping bool) int {\n\treturn findMatchedClosingSymbolsIndex(s, allowEscaping, '{', '}', 1)\n}\n\n// findMatchedClosingBracketIndex finds the matching `)` for a `(`.\nfunc findMatchedClosingBracketIndex(s string, allowEscaping bool) int {\n\treturn findMatchedClosingSymbolsIndex(s, allowEscaping, '(', ')', 0)\n}\n\n// findNextCommaIndex returns the next comma outside nested braces.\nfunc findNextCommaIndex(s string, allowEscaping bool) int {\n\talts := 1\n\tl := len(s)\n\tfor i := 0; i < l; i++ {\n\t\tif allowEscaping && s[i] == '\\\\' {\n\t\t\ti++\n\t\t} else if s[i] == '{' {\n\t\t\talts++\n\t\t} else if s[i] == '}' {\n\t\t\talts--\n\t\t} else if s[i] == ',' && alts == 1 {\n\t\t\treturn i\n\t\t}\n\t}\n\treturn -1\n}\n\nfunc findMatchedClosingSymbolsIndex(s string, allowEscaping bool, left, right uint8, begin int) int {\n\tl := len(s)\n\tfor i := 0; i < l; i++ {\n\t\tif allowEscaping && s[i] == '\\\\' {\n\t\t\ti++\n\t\t} else if s[i] == left {\n\t\t\tbegin++\n\t\t} else if s[i] == right {\n\t\t\tif begin--; begin == 0 {\n\t\t\t\treturn i\n\t\t\t}\n\t\t}\n\t}\n\treturn -1\n}\n" }, { "path": "components/execd/pkg/util/glob/match.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//\n// This code is based on or derived from doublestar\n// Copyright (c) 2014 Bob Matcuk\n// Licensed under MIT License\n// https://github.com/bmatcuk/doublestar/blob/master/LICENSE\n\npackage glob\n\nimport (\n\t\"path/filepath\"\n\t\"unicode/utf8\"\n\n\tglobutil \"github.com/bmatcuk/doublestar/v4\"\n)\n\n// PathMatch is filepath.Match compatible but honors doublestar semantics.\nfunc PathMatch(pattern, name string) (bool, error) {\n\treturn matchWithSeparator(pattern, name, filepath.Separator, true)\n}\n\nfunc matchWithSeparator(pattern, name string, separator rune, validate bool) (matched bool, err error) {\n\treturn doMatchWithSeparator(pattern, name, separator, validate, -1, -1, -1, -1, 0, 0)\n}\n\n//nolint:gocognit,nestif,gocyclo,maintidx\nfunc doMatchWithSeparator(pattern, name string, separator rune, validate bool, doublestarPatternBacktrack, doublestarNameBacktrack, starPatternBacktrack, starNameBacktrack, patIdx, nameIdx int) (matched bool, err error) {\n\tpatLen := len(pattern)\n\tnameLen := len(name)\n\tstartOfSegment := true\nMATCH:\n\tfor nameIdx < nameLen {\n\t\tif patIdx < patLen {\n\t\t\tswitch pattern[patIdx] {\n\t\t\tcase '*':\n\t\t\t\tif patIdx++; patIdx < patLen && pattern[patIdx] == '*' {\n\t\t\t\t\t// doublestar - must begin with a path separator, otherwise we'll\n\t\t\t\t\tpatIdx++\n\t\t\t\t\tif startOfSegment {\n\t\t\t\t\t\tif patIdx >= patLen {\n\t\t\t\t\t\t\t// pattern ends in `/**`: return true\n\t\t\t\t\t\t\treturn true, nil\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// doublestar must also end with a path separator, otherwise we're\n\t\t\t\t\t\tpatRune, patRuneLen := utf8.DecodeRuneInString(pattern[patIdx:])\n\t\t\t\t\t\tif patRune == separator {\n\t\t\t\t\t\t\tpatIdx += patRuneLen\n\n\t\t\t\t\t\t\tdoublestarPatternBacktrack = patIdx\n\t\t\t\t\t\t\tdoublestarNameBacktrack = nameIdx\n\t\t\t\t\t\t\tstarPatternBacktrack = -1\n\t\t\t\t\t\t\tstarNameBacktrack = -1\n\t\t\t\t\t\t\tcontinue\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tstartOfSegment = false\n\n\t\t\t\tstarPatternBacktrack = patIdx\n\t\t\t\tstarNameBacktrack = nameIdx\n\t\t\t\tcontinue\n\n\t\t\tcase '?':\n\t\t\t\tstartOfSegment = false\n\t\t\t\tnameRune, nameRuneLen := utf8.DecodeRuneInString(name[nameIdx:])\n\t\t\t\tif nameRune == separator {\n\t\t\t\t\t// `?` cannot match the separator\n\t\t\t\t\tbreak\n\t\t\t\t}\n\n\t\t\t\tpatIdx++\n\t\t\t\tnameIdx += nameRuneLen\n\t\t\t\tcontinue\n\n\t\t\tcase '[':\n\t\t\t\tstartOfSegment = false\n\t\t\t\tif patIdx++; patIdx >= patLen {\n\t\t\t\t\t// class didn't end\n\t\t\t\t\treturn false, globutil.ErrBadPattern\n\t\t\t\t}\n\t\t\t\tnameRune, nameRuneLen := utf8.DecodeRuneInString(name[nameIdx:])\n\n\t\t\t\tmatched := false\n\t\t\t\tnegate := pattern[patIdx] == '!' || pattern[patIdx] == '^'\n\t\t\t\tif negate {\n\t\t\t\t\tpatIdx++\n\t\t\t\t}\n\n\t\t\t\tif patIdx >= patLen || pattern[patIdx] == ']' {\n\t\t\t\t\t// class didn't end or empty character class\n\t\t\t\t\treturn false, globutil.ErrBadPattern\n\t\t\t\t}\n\n\t\t\t\tlast := utf8.MaxRune\n\t\t\t\tfor patIdx < patLen && pattern[patIdx] != ']' {\n\t\t\t\t\tpatRune, patRuneLen := utf8.DecodeRuneInString(pattern[patIdx:])\n\t\t\t\t\tpatIdx += patRuneLen\n\n\t\t\t\t\t// match a range\n\t\t\t\t\tif last < utf8.MaxRune && patRune == '-' && patIdx < patLen && pattern[patIdx] != ']' {\n\t\t\t\t\t\tif pattern[patIdx] == '\\\\' {\n\t\t\t\t\t\t\t// next character is escaped\n\t\t\t\t\t\t\tpatIdx++\n\t\t\t\t\t\t}\n\t\t\t\t\t\tpatRune, patRuneLen = utf8.DecodeRuneInString(pattern[patIdx:])\n\t\t\t\t\t\tpatIdx += patRuneLen\n\n\t\t\t\t\t\tif last <= nameRune && nameRune <= patRune {\n\t\t\t\t\t\t\tmatched = true\n\t\t\t\t\t\t\tbreak\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// didn't match range - reset `last`\n\t\t\t\t\t\tlast = utf8.MaxRune\n\t\t\t\t\t\tcontinue\n\t\t\t\t\t}\n\n\t\t\t\t\t// not a range - check if the next rune is escaped\n\t\t\t\t\tif patRune == '\\\\' {\n\t\t\t\t\t\tpatRune, patRuneLen = utf8.DecodeRuneInString(pattern[patIdx:])\n\t\t\t\t\t\tpatIdx += patRuneLen\n\t\t\t\t\t}\n\n\t\t\t\t\t// check if the rune matches\n\t\t\t\t\tif patRune == nameRune {\n\t\t\t\t\t\tmatched = true\n\t\t\t\t\t\tbreak\n\t\t\t\t\t}\n\n\t\t\t\t\t// no matches yet\n\t\t\t\t\tlast = patRune\n\t\t\t\t}\n\n\t\t\t\tif matched == negate {\n\t\t\t\t\t// failed to match - if we reached the end of the pattern, that means\n\t\t\t\t\tif patIdx >= patLen {\n\t\t\t\t\t\treturn false, globutil.ErrBadPattern\n\t\t\t\t\t}\n\t\t\t\t\tbreak\n\t\t\t\t}\n\n\t\t\t\tclosingIdx := findUnescapedByteIndex(pattern[patIdx:], ']', true)\n\t\t\t\tif closingIdx == -1 {\n\t\t\t\t\t// no closing `]`\n\t\t\t\t\treturn false, globutil.ErrBadPattern\n\t\t\t\t}\n\n\t\t\t\tpatIdx += closingIdx + 1\n\t\t\t\tnameIdx += nameRuneLen\n\t\t\t\tcontinue\n\t\t\tcase '!':\n\t\t\t\tnegateIdx := patIdx\n\t\t\t\t// begin index of (\n\t\t\t\tpatIdx++\n\t\t\t\tclosingIdx := findMatchedClosingBracketIndex(pattern[patIdx:], separator != '\\\\')\n\t\t\t\tif closingIdx == -1 {\n\t\t\t\t\treturn false, globutil.ErrBadPattern\n\t\t\t\t}\n\t\t\t\tclosingIdx += patIdx\n\n\t\t\t\tresult, err := doMatchWithSeparator(pattern[:negateIdx]+pattern[patIdx+1:closingIdx]+pattern[closingIdx+1:], name, separator, validate, doublestarPatternBacktrack, doublestarNameBacktrack, starPatternBacktrack, starNameBacktrack, negateIdx, nameIdx)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn false, err\n\t\t\t\t} else if !result {\n\t\t\t\t\treturn true, nil\n\t\t\t\t} else {\n\t\t\t\t\treturn false, nil\n\t\t\t\t}\n\t\t\tcase '{':\n\t\t\t\tstartOfSegment = false //nolint:ineffassign\n\t\t\t\tbeforeIdx := patIdx\n\t\t\t\tpatIdx++\n\t\t\t\tclosingIdx := findMatchedClosingAltIndex(pattern[patIdx:], separator != '\\\\')\n\t\t\t\tif closingIdx == -1 {\n\t\t\t\t\t// no closing `}`\n\t\t\t\t\treturn false, globutil.ErrBadPattern\n\t\t\t\t}\n\t\t\t\tclosingIdx += patIdx\n\n\t\t\t\tfor {\n\t\t\t\t\tcommaIdx := findNextCommaIndex(pattern[patIdx:closingIdx], separator != '\\\\')\n\t\t\t\t\tif commaIdx == -1 {\n\t\t\t\t\t\tbreak\n\t\t\t\t\t}\n\t\t\t\t\tcommaIdx += patIdx\n\n\t\t\t\t\tresult, err := doMatchWithSeparator(pattern[:beforeIdx]+pattern[patIdx:commaIdx]+pattern[closingIdx+1:], name, separator, validate, doublestarPatternBacktrack, doublestarNameBacktrack, starPatternBacktrack, starNameBacktrack, beforeIdx, nameIdx)\n\t\t\t\t\tif result || err != nil {\n\t\t\t\t\t\treturn result, err\n\t\t\t\t\t}\n\n\t\t\t\t\tpatIdx = commaIdx + 1\n\t\t\t\t}\n\t\t\t\treturn doMatchWithSeparator(pattern[:beforeIdx]+pattern[patIdx:closingIdx]+pattern[closingIdx+1:], name, separator, validate, doublestarPatternBacktrack, doublestarNameBacktrack, starPatternBacktrack, starNameBacktrack, beforeIdx, nameIdx)\n\n\t\t\tcase '\\\\':\n\t\t\t\tif separator != '\\\\' {\n\t\t\t\t\t// next rune is \"escaped\" in the pattern - literal match\n\t\t\t\t\tif patIdx++; patIdx >= patLen {\n\t\t\t\t\t\t// pattern ended\n\t\t\t\t\t\treturn false, globutil.ErrBadPattern\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tfallthrough\n\n\t\t\tdefault:\n\t\t\t\tpatRune, patRuneLen := utf8.DecodeRuneInString(pattern[patIdx:])\n\t\t\t\tnameRune, nameRuneLen := utf8.DecodeRuneInString(name[nameIdx:])\n\t\t\t\tif patRune != nameRune {\n\t\t\t\t\tif separator != '\\\\' && patIdx > 0 && pattern[patIdx-1] == '\\\\' {\n\t\t\t\t\t\t// if this rune was meant to be escaped, we need to move patIdx\n\t\t\t\t\t\tpatIdx--\n\t\t\t\t\t}\n\t\t\t\t\tbreak\n\t\t\t\t}\n\n\t\t\t\tpatIdx += patRuneLen\n\t\t\t\tnameIdx += nameRuneLen\n\t\t\t\tstartOfSegment = patRune == separator\n\t\t\t\tcontinue\n\t\t\t}\n\t\t}\n\n\t\tif starPatternBacktrack >= 0 {\n\t\t\t// `*` backtrack, but only if the `name` rune isn't the separator\n\t\t\tnameRune, nameRuneLen := utf8.DecodeRuneInString(name[starNameBacktrack:])\n\t\t\tif nameRune != separator {\n\t\t\t\tstarNameBacktrack += nameRuneLen\n\t\t\t\tpatIdx = starPatternBacktrack\n\t\t\t\tnameIdx = starNameBacktrack\n\t\t\t\tstartOfSegment = false\n\t\t\t\tcontinue\n\t\t\t}\n\t\t}\n\n\t\tif doublestarPatternBacktrack >= 0 {\n\t\t\t// `**` backtrack, advance `name` past next separator\n\t\t\tnameIdx = doublestarNameBacktrack\n\t\t\tfor nameIdx < nameLen {\n\t\t\t\tnameRune, nameRuneLen := utf8.DecodeRuneInString(name[nameIdx:])\n\t\t\t\tnameIdx += nameRuneLen\n\t\t\t\tif nameRune == separator {\n\t\t\t\t\tdoublestarNameBacktrack = nameIdx\n\t\t\t\t\tpatIdx = doublestarPatternBacktrack\n\t\t\t\t\tstartOfSegment = true\n\t\t\t\t\tcontinue MATCH\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif validate && patIdx < patLen && !isValidPattern(pattern[patIdx:], separator) {\n\t\t\treturn false, globutil.ErrBadPattern\n\t\t}\n\t\treturn false, nil\n\t}\n\n\tif nameIdx < nameLen {\n\t\t// we reached the end of `pattern` before the end of `name`\n\t\treturn false, nil\n\t}\n\n\t// we've reached the end of `name`; we've successfully matched if we've also\n\treturn isZeroLengthPattern(pattern[patIdx:], separator)\n}\n\n// nolint:nakedret\nfunc isZeroLengthPattern(pattern string, separator rune) (ret bool, err error) {\n\t// `/**` is a special case - a pattern such as `path/to/a/**` *should* match\n\tif pattern == \"\" || pattern == \"*\" || pattern == \"**\" || pattern == string(separator)+\"**\" {\n\t\treturn true, nil\n\t}\n\n\tif pattern[0] == '{' {\n\t\tclosingIdx := findMatchedClosingAltIndex(pattern[1:], separator != '\\\\')\n\t\tif closingIdx == -1 {\n\t\t\t// no closing '}'\n\t\t\treturn false, globutil.ErrBadPattern\n\t\t}\n\t\tclosingIdx += 1\n\n\t\tpatIdx := 1\n\t\tfor {\n\t\t\tcommaIdx := findNextCommaIndex(pattern[patIdx:closingIdx], separator != '\\\\')\n\t\t\tif commaIdx == -1 {\n\t\t\t\tbreak\n\t\t\t}\n\t\t\tcommaIdx += patIdx\n\n\t\t\tret, err = isZeroLengthPattern(pattern[patIdx:commaIdx]+pattern[closingIdx+1:], separator)\n\t\t\tif ret || err != nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tpatIdx = commaIdx + 1\n\t\t}\n\t\treturn isZeroLengthPattern(pattern[patIdx:closingIdx]+pattern[closingIdx+1:], separator)\n\t}\n\n\t// no luck - validate the rest of the pattern\n\tif !isValidPattern(pattern, separator) {\n\t\treturn false, globutil.ErrBadPattern\n\t}\n\treturn false, nil\n}\n" }, { "path": "components/execd/pkg/util/glob/match_benchmark_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage glob\n\nimport (\n\t\"path/filepath\"\n\t\"testing\"\n)\n\nfunc BenchmarkPathMatch(b *testing.B) {\n\tb.ReportAllocs()\n\tfor i := 0; i < b.N; i++ {\n\t\tfor _, tt := range matchTests {\n\t\t\tif tt.isStandard && tt.testOnDisk {\n\t\t\t\tpattern := filepath.FromSlash(tt.pattern)\n\t\t\t\ttestPath := filepath.FromSlash(tt.testPath)\n\t\t\t\tPathMatch(pattern, testPath)\n\t\t\t}\n\t\t}\n\t}\n}\n" }, { "path": "components/execd/pkg/util/glob/match_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//\n// This code is based on or derived from doublestar\n// Copyright (c) 2014 Bob Matcuk\n// Licensed under MIT License\n// https://github.com/bmatcuk/doublestar/blob/master/LICENSE\n\npackage glob\n\nimport (\n\t\"path/filepath\"\n\t\"runtime\"\n\t\"strings\"\n\t\"testing\"\n\n\tglobutil \"github.com/bmatcuk/doublestar/v4\"\n)\n\ntype MatchTest struct {\n\tpattern, testPath string\n\tshouldMatch bool\n\tshouldMatchGlob bool\n\texpectedErr error\n\texpectIOErr bool\n\texpectPatternNotExist bool\n\tisStandard bool\n\ttestOnDisk bool\n\tnumResults int\n\twinNumResults int\n}\n\n// Tests which contain escapes and symlinks will not work on Windows\nvar onWindows = runtime.GOOS == \"windows\"\n\nvar matchTests = []MatchTest{\n\t{\"\", \"\", true, false, nil, true, false, true, true, 0, 0},\n\t{\"*\", \"\", true, true, nil, false, false, true, false, 0, 0},\n\t{\"*\", \"/\", false, false, nil, false, false, true, false, 0, 0},\n\t{\"/*\", \"/\", true, true, nil, false, false, true, false, 0, 0},\n\t{\"/*\", \"/debug/\", false, false, nil, false, false, true, false, 0, 0},\n\t{\"/*\", \"//\", false, false, nil, false, false, true, false, 0, 0},\n\t{\"abc\", \"abc\", true, true, nil, false, false, true, true, 1, 1},\n\t{\"*\", \"abc\", true, true, nil, false, false, true, true, 22, 17},\n\t{\"*c\", \"abc\", true, true, nil, false, false, true, true, 2, 2},\n\t{\"*/\", \"a/\", true, true, nil, false, false, true, false, 0, 0},\n\t{\"a*\", \"a\", true, true, nil, false, false, true, true, 9, 9},\n\t{\"a*\", \"abc\", true, true, nil, false, false, true, true, 9, 9},\n\t{\"a*\", \"ab/c\", false, false, nil, false, false, true, true, 9, 9},\n\t{\"a*/b\", \"abc/b\", true, true, nil, false, false, true, true, 2, 2},\n\t{\"a*/b\", \"a/c/b\", false, false, nil, false, false, true, true, 2, 2},\n\t{\"a*/c/\", \"a/b\", false, false, nil, false, false, false, true, 1, 1},\n\t{\"a*b*c*d*e*\", \"axbxcxdxe\", true, true, nil, false, false, true, true, 3, 3},\n\t{\"a*b*c*d*e*/f\", \"axbxcxdxe/f\", true, true, nil, false, false, true, true, 2, 2},\n\t{\"a*b*c*d*e*/f\", \"axbxcxdxexxx/f\", true, true, nil, false, false, true, true, 2, 2},\n\t{\"a*b*c*d*e*/f\", \"axbxcxdxe/xxx/f\", false, false, nil, false, false, true, true, 2, 2},\n\t{\"a*b*c*d*e*/f\", \"axbxcxdxexxx/fff\", false, false, nil, false, false, true, true, 2, 2},\n\t{\"a*b?c*x\", \"abxbbxdbxebxczzx\", true, true, nil, false, false, true, true, 2, 2},\n\t{\"a*b?c*x\", \"abxbbxdbxebxczzy\", false, false, nil, false, false, true, true, 2, 2},\n\t{\"ab[c]\", \"abc\", true, true, nil, false, false, true, true, 1, 1},\n\t{\"ab[b-d]\", \"abc\", true, true, nil, false, false, true, true, 1, 1},\n\t{\"ab[e-g]\", \"abc\", false, false, nil, false, false, true, true, 0, 0},\n\t{\"ab[^c]\", \"abc\", false, false, nil, false, false, true, true, 0, 0},\n\t{\"ab[^b-d]\", \"abc\", false, false, nil, false, false, true, true, 0, 0},\n\t{\"ab[^e-g]\", \"abc\", true, true, nil, false, false, true, true, 1, 1},\n\t{\"a\\\\*b\", \"ab\", false, false, nil, false, true, true, !onWindows, 0, 0},\n\t{\"a?b\", \"aโ˜บb\", true, true, nil, false, false, true, true, 1, 1},\n\t{\"a[^a]b\", \"aโ˜บb\", true, true, nil, false, false, true, true, 1, 1},\n\t{\"a[!a]b\", \"aโ˜บb\", true, true, nil, false, false, false, true, 1, 1},\n\t{\"a???b\", \"aโ˜บb\", false, false, nil, false, false, true, true, 0, 0},\n\t{\"a[^a][^a][^a]b\", \"aโ˜บb\", false, false, nil, false, false, true, true, 0, 0},\n\t{\"[a-ฮถ]*\", \"ฮฑ\", true, true, nil, false, false, true, true, 20, 17},\n\t{\"*[a-ฮถ]\", \"A\", false, false, nil, false, false, true, true, 20, 17},\n\t{\"a?b\", \"a/b\", false, false, nil, false, false, true, true, 1, 1},\n\t{\"a*b\", \"a/b\", false, false, nil, false, false, true, true, 1, 1},\n\t{\"[\\\\]a]\", \"]\", true, true, nil, false, false, true, !onWindows, 2, 2},\n\t{\"[\\\\-]\", \"-\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"[x\\\\-]\", \"x\", true, true, nil, false, false, true, !onWindows, 2, 2},\n\t{\"[x\\\\-]\", \"-\", true, true, nil, false, false, true, !onWindows, 2, 2},\n\t{\"[x\\\\-]\", \"z\", false, false, nil, false, false, true, !onWindows, 2, 2},\n\t{\"[\\\\-x]\", \"x\", true, true, nil, false, false, true, !onWindows, 2, 2},\n\t{\"[\\\\-x]\", \"-\", true, true, nil, false, false, true, !onWindows, 2, 2},\n\t{\"[\\\\-x]\", \"a\", false, false, nil, false, false, true, !onWindows, 2, 2},\n\t{\"[]a]\", \"]\", false, false, globutil.ErrBadPattern, false, false, true, true, 0, 0},\n\t// doublestar, like bash, allows these when path.Match() does not\n\t{\"[-]\", \"-\", true, true, nil, false, false, false, !onWindows, 1, 0},\n\t{\"[x-]\", \"x\", true, true, nil, false, false, false, true, 2, 1},\n\t{\"[x-]\", \"-\", true, true, nil, false, false, false, !onWindows, 2, 1},\n\t{\"[x-]\", \"z\", false, false, nil, false, false, false, true, 2, 1},\n\t{\"[-x]\", \"x\", true, true, nil, false, false, false, true, 2, 1},\n\t{\"[-x]\", \"-\", true, true, nil, false, false, false, !onWindows, 2, 1},\n\t{\"[-x]\", \"a\", false, false, nil, false, false, false, true, 2, 1},\n\t{\"[a-b-d]\", \"a\", true, true, nil, false, false, false, true, 3, 2},\n\t{\"[a-b-d]\", \"b\", true, true, nil, false, false, false, true, 3, 2},\n\t{\"[a-b-d]\", \"-\", true, true, nil, false, false, false, !onWindows, 3, 2},\n\t{\"[a-b-d]\", \"c\", false, false, nil, false, false, false, true, 3, 2},\n\t{\"[a-b-x]\", \"x\", true, true, nil, false, false, false, true, 4, 3},\n\t{\"\\\\\", \"a\", false, false, globutil.ErrBadPattern, false, false, true, !onWindows, 0, 0},\n\t{\"[\", \"a\", false, false, globutil.ErrBadPattern, false, false, true, true, 0, 0},\n\t{\"[^\", \"a\", false, false, globutil.ErrBadPattern, false, false, true, true, 0, 0},\n\t{\"[^bc\", \"a\", false, false, globutil.ErrBadPattern, false, false, true, true, 0, 0},\n\t{\"a[\", \"a\", false, false, globutil.ErrBadPattern, false, false, true, true, 0, 0},\n\t{\"a[\", \"ab\", false, false, globutil.ErrBadPattern, false, false, true, true, 0, 0},\n\t{\"ad[\", \"ab\", false, false, globutil.ErrBadPattern, false, false, true, true, 0, 0},\n\t{\"*x\", \"xxx\", true, true, nil, false, false, true, true, 4, 4},\n\t{\"[abc]\", \"b\", true, true, nil, false, false, true, true, 3, 3},\n\t{\"**\", \"\", true, true, nil, false, false, false, false, 38, 38},\n\t{\"a/**\", \"a\", true, false, nil, false, false, false, true, 7, 7},\n\t{\"a/**\", \"a/\", true, true, nil, false, false, false, false, 7, 7},\n\t{\"a/**/\", \"a/\", true, true, nil, false, false, false, false, 4, 4},\n\t{\"a/**\", \"a/b\", true, true, nil, false, false, false, true, 7, 7},\n\t{\"a/**\", \"a/b/c\", true, true, nil, false, false, false, true, 7, 7},\n\t{\"**/c\", \"c\", true, true, nil, !onWindows, false, false, true, 5, 4},\n\t{\"**/c\", \"b/c\", true, true, nil, !onWindows, false, false, true, 5, 4},\n\t{\"**/c\", \"a/b/c\", true, true, nil, !onWindows, false, false, true, 5, 4},\n\t{\"**/c\", \"a/b\", false, false, nil, !onWindows, false, false, true, 5, 4},\n\t{\"**/c\", \"abcd\", false, false, nil, !onWindows, false, false, true, 5, 4},\n\t{\"**/c\", \"a/abc\", false, false, nil, !onWindows, false, false, true, 5, 4},\n\t{\"a/**/b\", \"a/b\", true, true, nil, false, false, false, true, 2, 2},\n\t{\"a/**/c\", \"a/b/c\", true, true, nil, false, false, false, true, 2, 2},\n\t{\"a/**/d\", \"a/b/c/d\", true, true, nil, false, false, false, true, 1, 1},\n\t{\"a/\\\\**\", \"a/b/c\", false, false, nil, false, false, false, !onWindows, 0, 0},\n\t{\"a/\\\\[*\\\\]\", \"a/bc\", false, false, nil, false, false, true, !onWindows, 0, 0},\n\t// this fails the FilepathGlob test on Windows\n\t{\"a/b/c\", \"a/b//c\", false, false, nil, false, false, true, !onWindows, 1, 1},\n\t// odd: Glob + filepath.Glob return results\n\t{\"a/\", \"a\", false, false, nil, false, false, true, false, 0, 0},\n\t{\"ab{c,d}\", \"abc\", true, true, nil, false, true, false, true, 1, 1},\n\t{\"ab{c,d,*}\", \"abcde\", true, true, nil, false, true, false, true, 5, 5},\n\t{\"ab{c,d}[\", \"abcd\", false, false, globutil.ErrBadPattern, false, false, false, true, 0, 0},\n\t{\"a{,bc}\", \"a\", true, true, nil, false, false, false, true, 2, 2},\n\t{\"a{,bc}\", \"abc\", true, true, nil, false, false, false, true, 2, 2},\n\t{\"a/{b/c,c/b}\", \"a/b/c\", true, true, nil, false, false, false, true, 2, 2},\n\t{\"a/{b/c,c/b}\", \"a/c/b\", true, true, nil, false, false, false, true, 2, 2},\n\t{\"a/a*{b,c}\", \"a/abc\", true, true, nil, false, false, false, true, 1, 1},\n\t{\"{a/{b,c},abc}\", \"a/b\", true, true, nil, false, false, false, true, 3, 3},\n\t{\"{a/{b,c},abc}\", \"a/c\", true, true, nil, false, false, false, true, 3, 3},\n\t{\"{a/{b,c},abc}\", \"abc\", true, true, nil, false, false, false, true, 3, 3},\n\t{\"{a/{b,c},abc}\", \"a/b/c\", false, false, nil, false, false, false, true, 3, 3},\n\t{\"{a/ab*}\", \"a/abc\", true, true, nil, false, false, false, true, 1, 1},\n\t{\"{a/*}\", \"a/b\", true, true, nil, false, false, false, true, 3, 3},\n\t{\"{a/abc}\", \"a/abc\", true, true, nil, false, false, false, true, 1, 1},\n\t{\"{a/b,a/c}\", \"a/c\", true, true, nil, false, false, false, true, 2, 2},\n\t{\"abc/**\", \"abc/b\", true, true, nil, false, false, false, true, 3, 3},\n\t{\"**/abc\", \"abc\", true, true, nil, !onWindows, false, false, true, 2, 2},\n\t{\"abc**\", \"abc/b\", false, false, nil, false, false, false, true, 3, 3},\n\t{\"**/*.txt\", \"abc/รŸtestรŸ.txt\", true, true, nil, !onWindows, false, false, true, 1, 1},\n\t{\"**/รŸ*\", \"abc/รŸtestรŸ.txt\", true, true, nil, !onWindows, false, false, true, 1, 1},\n\t{\"**/{a,b}\", \"a/b\", true, true, nil, !onWindows, false, false, true, 5, 5},\n\t// unfortunately, io/fs can't handle this, so neither can Glob =(\n\t{\"broken-symlink\", \"broken-symlink\", true, true, nil, false, false, true, false, 1, 1},\n\t{\"broken-symlink/*\", \"a\", false, false, nil, false, true, true, true, 0, 0},\n\t{\"broken*/*\", \"a\", false, false, nil, false, false, true, true, 0, 0},\n\t{\"working-symlink/c/*\", \"working-symlink/c/d\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"working-sym*/*\", \"working-symlink/c\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"b/**/f\", \"b/symlink-dir/f\", true, true, nil, false, false, false, !onWindows, 2, 2},\n\t{\"*/symlink-dir/*\", \"b/symlink-dir/f\", true, true, nil, !onWindows, false, true, !onWindows, 2, 2},\n\t{\"e/**\", \"e/**\", true, true, nil, false, false, false, !onWindows, 11, 6},\n\t{\"e/**\", \"e/*\", true, true, nil, false, false, false, !onWindows, 11, 6},\n\t{\"e/**\", \"e/?\", true, true, nil, false, false, false, !onWindows, 11, 6},\n\t{\"e/**\", \"e/[\", true, true, nil, false, false, false, true, 11, 6},\n\t{\"e/**\", \"e/]\", true, true, nil, false, false, false, true, 11, 6},\n\t{\"e/**\", \"e/[]\", true, true, nil, false, false, false, true, 11, 6},\n\t{\"e/**\", \"e/{\", true, true, nil, false, false, false, true, 11, 6},\n\t{\"e/**\", \"e/}\", true, true, nil, false, false, false, true, 11, 6},\n\t{\"e/**\", \"e/\\\\\", true, true, nil, false, false, false, !onWindows, 11, 6},\n\t{\"e/*\", \"e/*\", true, true, nil, false, false, true, !onWindows, 10, 5},\n\t{\"e/?\", \"e/?\", true, true, nil, false, false, true, !onWindows, 7, 4},\n\t{\"e/?\", \"e/*\", true, true, nil, false, false, true, !onWindows, 7, 4},\n\t{\"e/?\", \"e/[\", true, true, nil, false, false, true, true, 7, 4},\n\t{\"e/?\", \"e/]\", true, true, nil, false, false, true, true, 7, 4},\n\t{\"e/?\", \"e/{\", true, true, nil, false, false, true, true, 7, 4},\n\t{\"e/?\", \"e/}\", true, true, nil, false, false, true, true, 7, 4},\n\t{\"e/\\\\[\", \"e/[\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"e/[\", \"e/[\", false, false, globutil.ErrBadPattern, false, false, true, true, 0, 0},\n\t{\"e/]\", \"e/]\", true, true, nil, false, false, true, true, 1, 1},\n\t{\"e/\\\\]\", \"e/]\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"e/\\\\{\", \"e/{\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"e/\\\\}\", \"e/}\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"e/[\\\\*\\\\?]\", \"e/*\", true, true, nil, false, false, true, !onWindows, 2, 2},\n\t{\"e/[\\\\*\\\\?]\", \"e/?\", true, true, nil, false, false, true, !onWindows, 2, 2},\n\t{\"e/[\\\\*\\\\?]\", \"e/**\", false, false, nil, false, false, true, !onWindows, 2, 2},\n\t{\"e/[\\\\*\\\\?]?\", \"e/**\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"e/{\\\\*,\\\\?}\", \"e/*\", true, true, nil, false, false, false, !onWindows, 2, 2},\n\t{\"e/{\\\\*,\\\\?}\", \"e/?\", true, true, nil, false, false, false, !onWindows, 2, 2},\n\t{\"e/\\\\*\", \"e/*\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"e/\\\\?\", \"e/?\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"e/\\\\?\", \"e/**\", false, false, nil, false, false, true, !onWindows, 1, 1},\n\t{\"*\\\\}\", \"}\", true, true, nil, false, false, true, !onWindows, 1, 1},\n\t{\"nonexistent-path\", \"a\", false, false, nil, false, true, true, true, 0, 0},\n\t{\"nonexistent-path/\", \"a\", false, false, nil, false, true, true, true, 0, 0},\n\t{\"nonexistent-path/file\", \"a\", false, false, nil, false, true, true, true, 0, 0},\n\t{\"nonexistent-path/*\", \"a\", false, false, nil, false, true, true, true, 0, 0},\n\t{\"nonexistent-path/**\", \"a\", false, false, nil, false, true, true, true, 0, 0},\n\t{\"nopermission/*\", \"nopermission/file\", true, false, nil, true, false, true, !onWindows, 0, 0},\n\t{\"nopermission/dir/\", \"nopermission/dir\", false, false, nil, true, false, true, !onWindows, 0, 0},\n\t{\"nopermission/file\", \"nopermission/file\", true, false, nil, true, false, true, !onWindows, 0, 0},\n\t{\"node_modules/!(.cache)/**\", \"node_modules/others/file.txt\", true, true, nil, false, false, false, !onWindows, 0, 0},\n\t{\"node_modules/!(.cache)/**\", \"node_modules/.cache/file.txt\", false, false, nil, false, false, false, !onWindows, 0, 0},\n\t{\"node_modules/!(.cache)/**\", \"node_modules/file.txt\", true, false, nil, false, false, false, !onWindows, 0, 0},\n\t{\"node_modules/!(.cache)/**\", \"node_modules/others/others/file.txt\", true, true, nil, false, false, false, !onWindows, 0, 0},\n}\n\n// numResultsFilesOnly memoizes results with WithFilesOnly.\nvar numResultsFilesOnly []int\n\n// numResultsNoFollow memoizes results with WithNoFollow.\nvar numResultsNoFollow []int\n\n// numResultsAllOpts memoizes counts with every option enabled.\nvar numResultsAllOpts []int\n\nfunc TestValidatePattern(t *testing.T) {\n\tfor idx, tt := range matchTests {\n\t\ttestValidatePatternWith(t, idx, tt)\n\t}\n}\n\nfunc testValidatePatternWith(t *testing.T, idx int, tt MatchTest) {\n\tdefer func() {\n\t\tif r := recover(); r != nil {\n\t\t\tt.Errorf(\"#%v. Validate(%#q) panicked: %#v\", idx, tt.pattern, r)\n\t\t}\n\t}()\n\n\tresult := isValidPattern(tt.pattern, '/')\n\tif result != (tt.expectedErr == nil) {\n\t\tt.Errorf(\"#%v. ValidatePattern(%#q) = %v want %v\", idx, tt.pattern, result, !result)\n\t}\n}\n\nfunc TestPathMatch(t *testing.T) {\n\tfor idx, tt := range matchTests {\n\t\t// Even though we aren't actually matching paths on disk, we are using\n\t\tif tt.testOnDisk {\n\t\t\ttestPathMatchWith(t, idx, tt)\n\t\t}\n\t}\n}\n\nfunc testPathMatchWith(t *testing.T, idx int, tt MatchTest) {\n\tdefer func() {\n\t\tif r := recover(); r != nil {\n\t\t\tt.Errorf(\"#%v. Match(%#q, %#q) panicked: %#v\", idx, tt.pattern, tt.testPath, r)\n\t\t}\n\t}()\n\n\tpattern := filepath.FromSlash(tt.pattern)\n\ttestPath := filepath.FromSlash(tt.testPath)\n\tok, err := PathMatch(pattern, testPath)\n\tif ok != tt.shouldMatch || err != tt.expectedErr {\n\t\tt.Errorf(\"#%v. PathMatch(%#q, %#q) = %v, %v want %v, %v\", idx, pattern, testPath, ok, err, tt.shouldMatch, tt.expectedErr)\n\t}\n\n\tif tt.isStandard {\n\t\tstdOk, stdErr := filepath.Match(pattern, testPath)\n\t\tif ok != stdOk || !compareErrors(err, stdErr) {\n\t\t\tt.Errorf(\"#%v. PathMatch(%#q, %#q) != filepath.Match(...). Got %v, %v want %v, %v\", idx, pattern, testPath, ok, err, stdOk, stdErr)\n\t\t}\n\t}\n}\n\nfunc TestPathMatchFake(t *testing.T) {\n\t// This test fakes that our path separator is `\\\\` so we can test what it\n\tif onWindows {\n\t\treturn\n\t}\n\n\tfor idx, tt := range matchTests {\n\t\t// Even though we aren't actually matching paths on disk, we are using\n\t\tif tt.testOnDisk && !strings.Contains(tt.pattern, \"\\\\\") {\n\t\t\ttestPathMatchFakeWith(t, idx, tt)\n\t\t}\n\t}\n}\n\nfunc testPathMatchFakeWith(t *testing.T, idx int, tt MatchTest) {\n\tdefer func() {\n\t\tif r := recover(); r != nil {\n\t\t\tt.Errorf(\"#%v. Match(%#q, %#q) panicked: %#v\", idx, tt.pattern, tt.testPath, r)\n\t\t}\n\t}()\n\n\tpattern := strings.ReplaceAll(tt.pattern, \"/\", \"\\\\\")\n\ttestPath := strings.ReplaceAll(tt.testPath, \"/\", \"\\\\\")\n\tok, err := matchWithSeparator(pattern, testPath, '\\\\', true)\n\tif ok != tt.shouldMatch || err != tt.expectedErr {\n\t\tt.Errorf(\"#%v. PathMatch(%#q, %#q) = %v, %v want %v, %v\", idx, pattern, testPath, ok, err, tt.shouldMatch, tt.expectedErr)\n\t}\n}\n\nfunc compareErrors(a, b error) bool {\n\tif a == nil {\n\t\treturn b == nil\n\t}\n\treturn b != nil\n}\n" }, { "path": "components/execd/pkg/util/glob/pattern.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage glob\n\n// isValidPattern checks whether a glob pattern is well-formed.\n//\n//nolint:gocognit\nfunc isValidPattern(s string, separator rune) bool {\n\taltDepth := 0\n\tl := len(s)\nVALIDATE:\n\tfor i := 0; i < l; i++ {\n\t\tswitch s[i] {\n\t\tcase '\\\\':\n\t\t\tif separator != '\\\\' {\n\t\t\t\tif i++; i >= l {\n\t\t\t\t\treturn false\n\t\t\t\t}\n\t\t\t}\n\t\t\tcontinue\n\n\t\tcase '[':\n\t\t\tif i++; i >= l {\n\t\t\t\treturn false\n\t\t\t}\n\t\t\tif s[i] == '^' || s[i] == '!' {\n\t\t\t\ti++\n\t\t\t}\n\t\t\tif i >= l || s[i] == ']' {\n\t\t\t\treturn false\n\t\t\t}\n\n\t\t\tfor ; i < l; i++ {\n\t\t\t\tif separator != '\\\\' && s[i] == '\\\\' {\n\t\t\t\t\ti++\n\t\t\t\t} else if s[i] == ']' {\n\t\t\t\t\tcontinue VALIDATE\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn false\n\n\t\tcase '{':\n\t\t\taltDepth++\n\t\t\tcontinue\n\n\t\tcase '}':\n\t\t\tif altDepth == 0 {\n\t\t\t\treturn false\n\t\t\t}\n\t\t\taltDepth--\n\t\t\tcontinue\n\t\t}\n\t}\n\n\treturn altDepth == 0\n}\n" }, { "path": "components/execd/pkg/util/safego/safe.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage safego\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"net/http\"\n\t\"runtime\"\n\n\truntimeutil \"k8s.io/apimachinery/pkg/util/runtime\"\n)\n\nfunc InitPanicLogger(_ context.Context) {\n\truntimeutil.PanicHandlers = []func(context.Context, any){\n\t\tfunc(_ context.Context, r any) {\n\t\t\tif r == http.ErrAbortHandler { // nolint:errorlint\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tconst size = 64 << 10\n\t\t\tstacktrace := make([]byte, size)\n\t\t\tstacktrace = stacktrace[:runtime.Stack(stacktrace, false)]\n\t\t\tif _, ok := r.(string); ok {\n\t\t\t\tlog.Printf(\"Observed a panic: %s\\n%s\", r, stacktrace)\n\t\t\t} else {\n\t\t\t\tlog.Printf(\"Observed a panic: %#v (%v)\\n%s\", r, r, stacktrace)\n\t\t\t}\n\t\t},\n\t}\n}\n\nfunc init() {\n\truntimeutil.ReallyCrash = false\n}\n\nfunc Go(f func()) {\n\tgo func() {\n\t\tdefer runtimeutil.HandleCrash()\n\n\t\tf()\n\t}()\n}\n" }, { "path": "components/execd/pkg/util/safego/safe_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage safego\n\nimport (\n\t\"context\"\n\t\"sync\"\n\t\"testing\"\n)\n\nfunc Test_Go(t *testing.T) {\n\tctx, cancelFunc := context.WithCancel(context.Background())\n\tdefer cancelFunc()\n\n\tInitPanicLogger(ctx)\n\n\tvar wg sync.WaitGroup\n\twg.Add(1)\n\tGo(func() {\n\t\tdefer wg.Done()\n\t\tpanic(\"I'm done\")\n\t})\n\twg.Wait()\n}\n" }, { "path": "components/execd/pkg/web/controller/basic.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"strconv\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\ntype basicController struct {\n\tctx *gin.Context\n}\n\nfunc newBasicController(ctx *gin.Context) *basicController {\n\treturn &basicController{ctx: ctx}\n}\n\nfunc (c *basicController) RespondError(status int, code model.ErrorCode, message ...string) {\n\tresp := model.ErrorResponse{\n\t\tCode: code,\n\t\tMessage: \"\",\n\t}\n\tif len(message) > 0 {\n\t\tresp.Message = message[0]\n\t}\n\tc.ctx.JSON(status, resp)\n}\n\nfunc (c *basicController) RespondSuccess(data any) {\n\tif data == nil {\n\t\tc.ctx.Status(http.StatusOK)\n\t\treturn\n\t}\n\tc.ctx.JSON(http.StatusOK, data)\n}\n\nfunc (c *basicController) QueryInt64(query string, defaultValue int64) int64 {\n\tval, err := strconv.ParseInt(query, 10, 64)\n\tif err != nil {\n\t\treturn defaultValue\n\t}\n\treturn val\n}\n\nfunc (c *basicController) bindJSON(target any) error {\n\tdecoder := json.NewDecoder(c.ctx.Request.Body)\n\treturn decoder.Decode(target)\n}\n" }, { "path": "components/execd/pkg/web/controller/basic_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestBasicControllerRespondSuccess(t *testing.T) {\n\tctx, rec := newTestContext(http.MethodGet, \"/\", nil)\n\tctrl := &basicController{ctx: ctx}\n\n\tpayload := map[string]string{\"status\": \"ok\"}\n\tctrl.RespondSuccess(payload)\n\n\trequire.Equal(t, http.StatusOK, rec.Code)\n\tvar resp map[string]string\n\trequire.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))\n\trequire.Equal(t, \"ok\", resp[\"status\"])\n}\n\nfunc TestBasicControllerRespondError(t *testing.T) {\n\tctx, rec := newTestContext(http.MethodGet, \"/\", nil)\n\tctrl := &basicController{ctx: ctx}\n\n\tctrl.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, \"boom\")\n\n\trequire.Equal(t, http.StatusBadRequest, rec.Code)\n\tvar resp model.ErrorResponse\n\trequire.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))\n\trequire.Equal(t, model.ErrorCodeInvalidRequest, resp.Code)\n\trequire.Equal(t, \"boom\", resp.Message)\n}\n\nfunc setupBasicController(method string) (*basicController, *httptest.ResponseRecorder) {\n\tctx, w := newTestContext(method, \"/\", nil)\n\tctrl := &basicController{ctx: ctx}\n\treturn ctrl, w\n}\n\nfunc TestRespondSuccessWritesPayload(t *testing.T) {\n\tctrl, w := setupBasicController(http.MethodGet)\n\n\tpayload := map[string]string{\"status\": \"ok\"}\n\tctrl.RespondSuccess(payload)\n\n\trequire.Equal(t, http.StatusOK, w.Code)\n\tvar got map[string]string\n\trequire.NoError(t, json.Unmarshal(w.Body.Bytes(), &got))\n\trequire.Equal(t, \"ok\", got[\"status\"])\n}\n\nfunc TestRespondErrorAddsCodeAndMessage(t *testing.T) {\n\tctrl, w := setupBasicController(http.MethodGet)\n\n\tctrl.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, \"invalid payload\")\n\n\trequire.Equal(t, http.StatusBadRequest, w.Code)\n\tvar got model.ErrorResponse\n\trequire.NoError(t, json.Unmarshal(w.Body.Bytes(), &got))\n\trequire.Equal(t, model.ErrorCodeInvalidRequest, got.Code)\n\trequire.Equal(t, \"invalid payload\", got.Message)\n}\n\nfunc TestQueryInt64(t *testing.T) {\n\tctrl := &basicController{}\n\n\ttests := []struct {\n\t\tname string\n\t\tquery string\n\t\tdef int64\n\t\texpected int64\n\t}{\n\t\t{name: \"valid number\", query: \"42\", def: 0, expected: 42},\n\t\t{name: \"empty uses default\", query: \"\", def: 5, expected: 5},\n\t\t{name: \"invalid uses default\", query: \"not-a-number\", def: -1, expected: -1},\n\t\t{name: \"negative number\", query: \"-10\", def: 0, expected: -10},\n\t}\n\n\tfor _, tt := range tests {\n\t\tt.Run(tt.name, func(t *testing.T) {\n\t\t\tgot := ctrl.QueryInt64(tt.query, tt.def)\n\t\t\trequire.Equalf(t, tt.expected, got, \"QueryInt64(%q, %d)\", tt.query, tt.def)\n\t\t})\n\t}\n}\n" }, { "path": "components/execd/pkg/web/controller/codeinterpreting.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"sync\"\n\t\"time\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/flag\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/runtime\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\nvar codeRunner *runtime.Controller\n\nfunc InitCodeRunner() {\n\tcodeRunner = runtime.NewController(flag.JupyterServerHost, flag.JupyterServerToken)\n}\n\n// CodeInterpretingController handles code execution entrypoints.\ntype CodeInterpretingController struct {\n\t*basicController\n\n\t// chunkWriter serializes SSE event writes to prevent interleaved output.\n\tchunkWriter sync.Mutex\n}\n\nfunc NewCodeInterpretingController(ctx *gin.Context) *CodeInterpretingController {\n\treturn &CodeInterpretingController{\n\t\tbasicController: newBasicController(ctx),\n\t}\n}\n\n// CreateContext creates a new code execution context.\nfunc (c *CodeInterpretingController) CreateContext() {\n\tvar request model.CodeContextRequest\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tsession, err := codeRunner.CreateContext(&runtime.CreateContextRequest{\n\t\tLanguage: runtime.Language(request.Language),\n\t\tCwd: request.Cwd,\n\t})\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error creating code context. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tresp := model.CodeContext{\n\t\tID: session,\n\t\tCodeContextRequest: request,\n\t}\n\tc.RespondSuccess(resp)\n}\n\n// InterruptCode interrupts the execution of running code in a session.\nfunc (c *CodeInterpretingController) InterruptCode() {\n\tc.interrupt()\n}\n\n// RunCode executes code in a context and streams output via SSE.\nfunc (c *CodeInterpretingController) RunCode() {\n\tvar request model.RunCodeRequest\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\terr := request.Validate()\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"invalid request, validation error %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tctx, cancel := context.WithCancel(c.ctx.Request.Context())\n\tdefer cancel()\n\trunCodeRequest := c.buildExecuteCodeRequest(request)\n\teventsHandler := c.setServerEventsHandler(ctx)\n\trunCodeRequest.Hooks = eventsHandler\n\n\tc.setupSSEResponse()\n\terr = codeRunner.Execute(runCodeRequest)\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error running codes %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\ttime.Sleep(flag.ApiGracefulShutdownTimeout)\n}\n\n// GetContext returns a specific code context by id.\nfunc (c *CodeInterpretingController) GetContext() {\n\tcontextID := c.ctx.Param(\"contextId\")\n\tif contextID == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing path parameter 'contextId'\",\n\t\t)\n\t\treturn\n\t}\n\n\tcodeContext, err := codeRunner.GetContext(contextID)\n\tif err != nil {\n\t\tif errors.Is(err, runtime.ErrContextNotFound) {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusNotFound,\n\t\t\t\tmodel.ErrorCodeContextNotFound,\n\t\t\t\tfmt.Sprintf(\"context %s not found\", contextID),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error getting code context %s. %v\", contextID, err),\n\t\t)\n\t\treturn\n\t}\n\tc.RespondSuccess(codeContext)\n}\n\n// ListContexts returns active code contexts, optionally filtered by language.\nfunc (c *CodeInterpretingController) ListContexts() {\n\tlanguage := c.ctx.Query(\"language\")\n\n\tcontexts, err := codeRunner.ListContext(language)\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\terr.Error(),\n\t\t)\n\t\treturn\n\t}\n\n\tc.RespondSuccess(contexts)\n}\n\n// DeleteContextsByLanguage deletes all contexts for a given language.\nfunc (c *CodeInterpretingController) DeleteContextsByLanguage() {\n\tlanguage := c.ctx.Query(\"language\")\n\tif language == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing query parameter 'language'\",\n\t\t)\n\t\treturn\n\t}\n\n\terr := codeRunner.DeleteLanguageContext(runtime.Language(language))\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error deleting code context %s. %v\", language, err),\n\t\t)\n\t\treturn\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// DeleteContext deletes a specific code context by id.\nfunc (c *CodeInterpretingController) DeleteContext() {\n\tcontextID := c.ctx.Param(\"contextId\")\n\tif contextID == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing path parameter 'contextId'\",\n\t\t)\n\t\treturn\n\t}\n\n\terr := codeRunner.DeleteContext(contextID)\n\tif err != nil {\n\t\tif errors.Is(err, runtime.ErrContextNotFound) {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusNotFound,\n\t\t\t\tmodel.ErrorCodeContextNotFound,\n\t\t\t\tfmt.Sprintf(\"context %s not found\", contextID),\n\t\t\t)\n\t\t\treturn\n\t\t} else {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error deleting code context %s. %v\", contextID, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// CreateSession creates a new bash session (create_session API).\n// An empty body is allowed and is treated as default options (no cwd override).\nfunc (c *CodeInterpretingController) CreateSession() {\n\tvar request model.CreateSessionRequest\n\tif err := c.bindJSON(&request); err != nil && !errors.Is(err, io.EOF) {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tsessionID, err := codeRunner.CreateBashSession(&runtime.CreateContextRequest{\n\t\tCwd: request.Cwd,\n\t})\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error creating session. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tc.RespondSuccess(model.CreateSessionResponse{SessionID: sessionID})\n}\n\n// RunInSession runs code in an existing bash session and streams output via SSE (run_in_session API).\nfunc (c *CodeInterpretingController) RunInSession() {\n\tsessionID := c.ctx.Param(\"sessionId\")\n\tif sessionID == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing path parameter 'sessionId'\",\n\t\t)\n\t\treturn\n\t}\n\n\tvar request model.RunInSessionRequest\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\tif err := request.Validate(); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"invalid request. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\ttimeout := time.Duration(request.TimeoutMs) * time.Millisecond\n\trunReq := &runtime.ExecuteCodeRequest{\n\t\tLanguage: runtime.Bash,\n\t\tContext: sessionID,\n\t\tCode: request.Code,\n\t\tCwd: request.Cwd,\n\t\tTimeout: timeout,\n\t}\n\tctx, cancel := context.WithCancel(c.ctx.Request.Context())\n\tdefer cancel()\n\trunReq.Hooks = c.setServerEventsHandler(ctx)\n\n\tc.setupSSEResponse()\n\terr := codeRunner.RunInBashSession(ctx, runReq)\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error running in session. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\ttime.Sleep(flag.ApiGracefulShutdownTimeout)\n}\n\n// DeleteSession deletes a bash session (delete_session API).\nfunc (c *CodeInterpretingController) DeleteSession() {\n\tsessionID := c.ctx.Param(\"sessionId\")\n\tif sessionID == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing path parameter 'sessionId'\",\n\t\t)\n\t\treturn\n\t}\n\n\terr := codeRunner.DeleteBashSession(sessionID)\n\tif err != nil {\n\t\tif errors.Is(err, runtime.ErrContextNotFound) {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusNotFound,\n\t\t\t\tmodel.ErrorCodeContextNotFound,\n\t\t\t\tfmt.Sprintf(\"session %s not found\", sessionID),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error deleting session %s. %v\", sessionID, err),\n\t\t)\n\t\treturn\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// buildExecuteCodeRequest converts a RunCodeRequest to runtime format.\nfunc (c *CodeInterpretingController) buildExecuteCodeRequest(request model.RunCodeRequest) *runtime.ExecuteCodeRequest {\n\treq := &runtime.ExecuteCodeRequest{\n\t\tLanguage: runtime.Language(request.Context.Language),\n\t\tCode: request.Code,\n\t\tContext: request.Context.ID,\n\t}\n\n\tif req.Language == \"\" {\n\t\treq.Language = runtime.Command\n\t}\n\n\treturn req\n}\n\nfunc (c *CodeInterpretingController) interrupt() {\n\tsession := c.ctx.Query(\"id\")\n\tif session == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing query parameter 'id'\",\n\t\t)\n\t\treturn\n\t}\n\n\terr := codeRunner.Interrupt(session)\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error interruptting code context. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tc.RespondSuccess(nil)\n}\n" }, { "path": "components/execd/pkg/web/controller/codeinterpreting_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"testing\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/runtime\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestBuildExecuteCodeRequestDefaultsToCommand(t *testing.T) {\n\tctrl := &CodeInterpretingController{}\n\treq := model.RunCodeRequest{\n\t\tCode: \"echo 1\",\n\t\tContext: model.CodeContext{\n\t\t\tID: \"session-1\",\n\t\t\tCodeContextRequest: model.CodeContextRequest{},\n\t\t},\n\t}\n\n\texecReq := ctrl.buildExecuteCodeRequest(req)\n\n\trequire.Equal(t, runtime.Command, execReq.Language, \"expected default language\")\n\trequire.Equal(t, \"session-1\", execReq.Context)\n\trequire.Equal(t, \"echo 1\", execReq.Code)\n}\n\nfunc TestBuildExecuteCodeRequestRespectsLanguage(t *testing.T) {\n\tctrl := &CodeInterpretingController{}\n\treq := model.RunCodeRequest{\n\t\tCode: \"print(1)\",\n\t\tContext: model.CodeContext{\n\t\t\tID: \"session-2\",\n\t\t\tCodeContextRequest: model.CodeContextRequest{\n\t\t\t\tLanguage: \"python\",\n\t\t\t},\n\t\t},\n\t}\n\n\texecReq := ctrl.buildExecuteCodeRequest(req)\n\n\trequire.Equal(t, runtime.Language(\"python\"), execReq.Language)\n}\n\nfunc TestGetContext_NotFoundReturns404(t *testing.T) {\n\tctx, w := newTestContext(http.MethodGet, \"/code/contexts/missing\", nil)\n\tctx.Params = append(ctx.Params, gin.Param{Key: \"contextId\", Value: \"missing\"})\n\tctrl := NewCodeInterpretingController(ctx)\n\n\tprevious := codeRunner\n\tcodeRunner = runtime.NewController(\"\", \"\")\n\tt.Cleanup(func() { codeRunner = previous })\n\n\tctrl.GetContext()\n\n\trequire.Equal(t, http.StatusNotFound, w.Code)\n\n\tvar resp model.ErrorResponse\n\trequire.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))\n\trequire.Equal(t, model.ErrorCodeContextNotFound, resp.Code)\n\trequire.Equal(t, \"context missing not found\", resp.Message)\n}\n\nfunc TestGetContext_MissingIDReturns400(t *testing.T) {\n\tctx, w := newTestContext(http.MethodGet, \"/code/contexts/\", nil)\n\tctrl := NewCodeInterpretingController(ctx)\n\n\tctrl.GetContext()\n\n\trequire.Equal(t, http.StatusBadRequest, w.Code)\n\n\tvar resp model.ErrorResponse\n\trequire.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))\n\trequire.Equal(t, model.ErrorCodeMissingQuery, resp.Code)\n\trequire.Equal(t, \"missing path parameter 'contextId'\", resp.Message)\n}\n" }, { "path": "components/execd/pkg/web/controller/command.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"strconv\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/flag\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/runtime\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\n// RunCommand executes a shell command and streams the output via SSE.\nfunc (c *CodeInterpretingController) RunCommand() {\n\tvar request model.RunCommandRequest\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\terr := request.Validate()\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"invalid request, validation error %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tctx, cancel := context.WithCancel(c.ctx.Request.Context())\n\tdefer cancel()\n\n\trunCodeRequest := c.buildExecuteCommandRequest(request)\n\teventsHandler := c.setServerEventsHandler(ctx)\n\trunCodeRequest.Hooks = eventsHandler\n\n\tc.setupSSEResponse()\n\terr = codeRunner.Execute(runCodeRequest)\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error running commands %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\ttime.Sleep(flag.ApiGracefulShutdownTimeout)\n}\n\n// InterruptCommand stops a running shell command session.\nfunc (c *CodeInterpretingController) InterruptCommand() {\n\tc.interrupt()\n}\n\n// GetCommandStatus returns command status by id.\nfunc (c *CodeInterpretingController) GetCommandStatus() {\n\tcommandID := c.ctx.Param(\"id\")\n\tif commandID == \"\" {\n\t\tc.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, \"missing command execution id\")\n\t\treturn\n\t}\n\n\tstatus, err := codeRunner.GetCommandStatus(commandID)\n\tif err != nil {\n\t\tc.RespondError(http.StatusNotFound, model.ErrorCodeInvalidRequest, err.Error())\n\t\treturn\n\t}\n\n\tresp := model.CommandStatusResponse{\n\t\tID: status.Session,\n\t\tRunning: status.Running,\n\t\tExitCode: status.ExitCode,\n\t\tError: status.Error,\n\t\tContent: status.Content,\n\t}\n\tif !status.StartedAt.IsZero() {\n\t\tresp.StartedAt = status.StartedAt\n\t}\n\tif status.FinishedAt != nil {\n\t\tresp.FinishedAt = status.FinishedAt\n\t}\n\n\tc.RespondSuccess(resp)\n}\n\n// GetBackgroundCommandOutput returns accumulated stdout/stderr for a command session as plain text.\nfunc (c *CodeInterpretingController) GetBackgroundCommandOutput() {\n\tid := c.ctx.Param(\"id\")\n\tif id == \"\" {\n\t\tc.RespondError(http.StatusBadRequest, model.ErrorCodeMissingQuery, \"missing command execution id\")\n\t\treturn\n\t}\n\n\tcursor := c.QueryInt64(c.ctx.Query(\"cursor\"), 0)\n\toutput, lastCursor, err := codeRunner.SeekBackgroundCommandOutput(id, cursor)\n\tif err != nil {\n\t\tc.RespondError(http.StatusBadRequest, model.ErrorCodeInvalidRequest, err.Error())\n\t\treturn\n\t}\n\n\tc.ctx.Header(\"EXECD-COMMANDS-TAIL-CURSOR\", strconv.FormatInt(lastCursor, 10))\n\tc.ctx.Header(\"Content-Type\", \"text/plain; charset=utf-8\")\n\tc.ctx.String(http.StatusOK, \"%s\", output)\n}\n\nfunc (c *CodeInterpretingController) buildExecuteCommandRequest(request model.RunCommandRequest) *runtime.ExecuteCodeRequest {\n\ttimeout := time.Duration(request.TimeoutMs) * time.Millisecond\n\tif request.Background {\n\t\treturn &runtime.ExecuteCodeRequest{\n\t\t\tLanguage: runtime.BackgroundCommand,\n\t\t\tCode: request.Command,\n\t\t\tCwd: request.Cwd,\n\t\t\tTimeout: timeout,\n\t\t\tGid: request.Gid,\n\t\t\tUid: request.Uid,\n\t\t\tEnvs: request.Envs,\n\t\t}\n\t} else {\n\t\treturn &runtime.ExecuteCodeRequest{\n\t\t\tLanguage: runtime.Command,\n\t\t\tCode: request.Command,\n\t\t\tCwd: request.Cwd,\n\t\t\tTimeout: timeout,\n\t\t\tGid: request.Gid,\n\t\t\tUid: request.Uid,\n\t\t\tEnvs: request.Envs,\n\t\t}\n\t}\n}\n" }, { "path": "components/execd/pkg/web/controller/command_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"reflect\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/runtime\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestBuildExecuteCommandRequestForwardsEnvs(t *testing.T) {\n\tctrl := &CodeInterpretingController{}\n\tenvs := map[string]string{\"FOO\": \"bar\", \"BAZ\": \"qux\"}\n\treq := model.RunCommandRequest{\n\t\tCommand: \"echo hi\",\n\t\tCwd: \"/tmp\",\n\t\tEnvs: envs,\n\t}\n\n\texecReq := ctrl.buildExecuteCommandRequest(req)\n\n\trequire.Equal(t, runtime.Command, execReq.Language)\n\trequire.True(t, reflect.DeepEqual(execReq.Envs, envs), \"expected envs to be forwarded\")\n\trequire.Equal(t, \"/tmp\", execReq.Cwd)\n}\n\nfunc TestBuildExecuteCommandRequestForwardsEnvsBackground(t *testing.T) {\n\tctrl := &CodeInterpretingController{}\n\tenvs := map[string]string{\"FOO\": \"bar\"}\n\treq := model.RunCommandRequest{\n\t\tCommand: \"echo hi\",\n\t\tBackground: true,\n\t\tEnvs: envs,\n\t}\n\n\texecReq := ctrl.buildExecuteCommandRequest(req)\n\n\trequire.Equal(t, runtime.BackgroundCommand, execReq.Language)\n\trequire.True(t, reflect.DeepEqual(execReq.Envs, envs), \"expected envs to be forwarded\")\n}\n\nfunc setupCommandController(method, path string) (*CodeInterpretingController, *httptest.ResponseRecorder) {\n\tctx, w := newTestContext(method, path, nil)\n\tctrl := NewCodeInterpretingController(ctx)\n\treturn ctrl, w\n}\n\nfunc TestGetCommandStatus_MissingID(t *testing.T) {\n\tctrl, w := setupCommandController(http.MethodGet, \"/command/status/\")\n\n\tctrl.GetCommandStatus()\n\n\trequire.Equal(t, http.StatusBadRequest, w.Code)\n\n\tvar resp model.ErrorResponse\n\trequire.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))\n\trequire.Equal(t, model.ErrorCodeInvalidRequest, resp.Code)\n\trequire.Equal(t, \"missing command execution id\", resp.Message)\n}\n\nfunc TestGetBackgroundCommandOutput_MissingID(t *testing.T) {\n\tctrl, w := setupCommandController(http.MethodGet, \"/command/logs/\")\n\n\tctrl.GetBackgroundCommandOutput()\n\n\trequire.Equal(t, http.StatusBadRequest, w.Code)\n\n\tvar resp model.ErrorResponse\n\trequire.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))\n\trequire.Equal(t, model.ErrorCodeMissingQuery, resp.Code)\n\trequire.Equal(t, \"missing command execution id\", resp.Message)\n}\n" }, { "path": "components/execd/pkg/web/controller/filesystem.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build !windows\n// +build !windows\n\npackage controller\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n\t\"os/user\"\n\t\"path/filepath\"\n\t\"strconv\"\n\t\"strings\"\n\t\"syscall\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/util/glob\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\n// FilesystemController handles file system operations\ntype FilesystemController struct {\n\t*basicController\n}\n\nfunc NewFilesystemController(ctx *gin.Context) *FilesystemController {\n\treturn &FilesystemController{basicController: newBasicController(ctx)}\n}\n\nfunc (c *FilesystemController) handleFileError(err error) {\n\tif os.IsNotExist(err) {\n\t\tc.RespondError(\n\t\t\thttp.StatusNotFound,\n\t\t\tmodel.ErrorCodeFileNotFound,\n\t\t\tfmt.Sprintf(\"file not found. %v\", err),\n\t\t)\n\t} else {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error accessing file: %v\", err),\n\t\t)\n\t}\n}\n\n// GetFilesInfo retrieves metadata for specified file paths\nfunc (c *FilesystemController) GetFilesInfo() {\n\tpaths := c.ctx.QueryArray(\"path\")\n\tif len(paths) == 0 {\n\t\tc.RespondSuccess(make(map[string]model.FileInfo))\n\t\treturn\n\t}\n\n\tresp := make(map[string]model.FileInfo)\n\tfor _, filePath := range paths {\n\t\tfileInfo, err := GetFileInfo(filePath)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t\tresp[filePath] = fileInfo\n\t}\n\n\tc.RespondSuccess(resp)\n}\n\n// RemoveFiles deletes specified files\nfunc (c *FilesystemController) RemoveFiles() {\n\tpaths := c.ctx.QueryArray(\"path\")\n\tfor _, filePath := range paths {\n\t\tif err := DeleteFile(filePath); err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error removing file %s. %v\", filePath, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// ChmodFiles changes file permissions for specified files\nfunc (c *FilesystemController) ChmodFiles() {\n\tvar request map[string]model.Permission\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tfor file, item := range request {\n\t\terr := ChmodFile(file, item)\n\t\tif err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error changing permissions for %s. %v\", file, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// RenameFiles renames or moves files to new paths\nfunc (c *FilesystemController) RenameFiles() {\n\tvar request []model.RenameFileItem\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tfor _, renameItem := range request {\n\t\tif err := RenameFile(renameItem); err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// MakeDirs creates directories with specified permissions\nfunc (c *FilesystemController) MakeDirs() {\n\tvar request map[string]model.Permission\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tfor dir, perm := range request {\n\t\tif err := MakeDir(dir, perm); err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// RemoveDirs recursively removes directories\nfunc (c *FilesystemController) RemoveDirs() {\n\tpaths := c.ctx.QueryArray(\"path\")\n\tfor _, dir := range paths {\n\t\tif err := os.RemoveAll(dir); err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error removing directory %s. %v\", dir, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// SearchFiles searches for files matching a pattern in a directory\nfunc (c *FilesystemController) SearchFiles() {\n\tpath := c.ctx.Query(\"path\")\n\tif path == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing query parameter 'path'\",\n\t\t)\n\t\treturn\n\t}\n\n\tpath, err := filepath.Abs(path)\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error converting path %s to absolute. %v\", path, err),\n\t\t)\n\t\treturn\n\t}\n\n\t_, err = os.Stat(path)\n\tif err != nil {\n\t\tc.handleFileError(err)\n\t\treturn\n\t}\n\n\tpattern := c.ctx.Query(\"pattern\")\n\tif pattern == \"\" {\n\t\tpattern = \"**\"\n\t}\n\n\tfiles := make([]model.FileInfo, 0, 16)\n\terr = filepath.Walk(path, func(filePath string, info os.FileInfo, err error) error {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn nil\n\t\t}\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"error accessing path %s: %w\", filePath, err)\n\t\t}\n\t\tif info.IsDir() {\n\t\t\treturn nil\n\t\t}\n\n\t\tmatch, err := glob.PathMatch(pattern, info.Name())\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"invalid pattern %s: %w\", pattern, err)\n\t\t}\n\n\t\tif match {\n\t\t\tsys := info.Sys().(*syscall.Stat_t)\n\n\t\t\towner, err := user.LookupId(strconv.FormatUint(uint64(sys.Uid), 10))\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"error lookup owner for file %s: %w\", filePath, err)\n\t\t\t}\n\n\t\t\tgroup, err := user.LookupGroupId(strconv.FormatUint(uint64(sys.Gid), 10))\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"error lookup group for file %s: %w\", filePath, err)\n\t\t\t}\n\n\t\t\tfiles = append(files, model.FileInfo{\n\t\t\t\tPath: filePath,\n\t\t\t\tSize: info.Size(),\n\t\t\t\tModifiedAt: info.ModTime(),\n\t\t\t\tCreatedAt: getFileCreateTime(info),\n\t\t\t\tPermission: model.Permission{\n\t\t\t\t\tOwner: owner.Username,\n\t\t\t\t\tGroup: group.Name,\n\t\t\t\t\tMode: func() int {\n\t\t\t\t\t\tmode := strconv.FormatInt(int64(info.Mode().Perm()), 8)\n\t\t\t\t\t\ti, _ := strconv.Atoi(mode)\n\t\t\t\t\t\treturn i\n\t\t\t\t\t}(),\n\t\t\t\t},\n\t\t\t})\n\t\t}\n\n\t\treturn nil\n\t})\n\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error searching files. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tc.RespondSuccess(files)\n}\n\n// ReplaceContent replaces text content in specified files\nfunc (c *FilesystemController) ReplaceContent() {\n\tvar request map[string]model.ReplaceFileContentItem\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tfor file, item := range request {\n\t\tfile, err := filepath.Abs(file)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\n\t\tif _, err = os.Stat(file); err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\n\t\tcontent, err := os.ReadFile(file)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\n\t\tfileInfo, err := os.Stat(file)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t\tmode := fileInfo.Mode()\n\n\t\tnewContent := strings.ReplaceAll(string(content), item.Old, item.New)\n\n\t\terr = os.WriteFile(file, []byte(newContent), mode)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n" }, { "path": "components/execd/pkg/web/controller/filesystem_download.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"net/url\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"strconv\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\n// DownloadFile serves a file for download with support for range requests.\nfunc (c *FilesystemController) DownloadFile() {\n\tfilePath := c.ctx.Query(\"path\")\n\tif filePath == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing query parameter 'path'\",\n\t\t)\n\t\treturn\n\t}\n\n\tfile, err := os.Open(filePath)\n\tif err != nil {\n\t\tc.handleFileError(err)\n\t\treturn\n\t}\n\tdefer file.Close()\n\n\tfileInfo, err := file.Stat()\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error getting file stat info: %s. %v\", filePath, err),\n\t\t)\n\t\treturn\n\t}\n\n\tc.ctx.Header(\"Content-Type\", \"application/octet-stream\")\n\tc.ctx.Header(\"Content-Disposition\", formatContentDisposition(filepath.Base(filePath)))\n\tc.ctx.Header(\"Content-Length\", strconv.FormatInt(fileInfo.Size(), 10))\n\n\tif rangeHeader := c.ctx.GetHeader(\"Range\"); rangeHeader != \"\" {\n\t\tranges, err := ParseRange(rangeHeader, fileInfo.Size())\n\t\tif err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusRequestedRangeNotSatisfiable,\n\t\t\t\tmodel.ErrorCodeUnknown,\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t\tif len(ranges) > 0 {\n\t\t\tr := ranges[0]\n\t\t\tc.ctx.Status(http.StatusPartialContent)\n\t\t\tc.ctx.Header(\"Content-Range\", fmt.Sprintf(\"bytes %d-%d/%d\", r.start, r.start+r.length-1, fileInfo.Size()))\n\t\t\tc.ctx.Header(\"Content-Length\", strconv.FormatInt(r.length, 10))\n\n\t\t\t_, _ = file.Seek(r.start, io.SeekStart)\n\t\t\t_, _ = io.CopyN(c.ctx.Writer, file, r.length)\n\t\t\treturn\n\t\t}\n\t}\n\n\thttp.ServeContent(c.ctx.Writer, c.ctx.Request, filepath.Base(filePath), fileInfo.ModTime(), file)\n}\n\n// formatContentDisposition formats the Content-Disposition header value with proper\n// encoding for non-ASCII filenames according to RFC 6266 and RFC 5987.\nfunc formatContentDisposition(filename string) string {\n\t// Check if filename contains non-ASCII characters\n\tneedsEncoding := false\n\tfor _, r := range filename {\n\t\tif r > 127 {\n\t\t\tneedsEncoding = true\n\t\t\tbreak\n\t\t}\n\t}\n\n\tif !needsEncoding {\n\t\treturn \"attachment; filename=\\\"\" + filename + \"\\\"\"\n\t}\n\n\t// Use RFC 5987 encoding for non-ASCII filenames\n\t// Format: attachment; filename=\"fallback\"; filename*=UTF-8''encoded_name\n\tencodedFilename := url.PathEscape(filename)\n\treturn \"attachment; filename=\\\"\" + encodedFilename + \"\\\"; filename*=UTF-8''\" + encodedFilename\n}\n" }, { "path": "components/execd/pkg/web/controller/filesystem_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"net/url\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc newFilesystemController(t *testing.T, method, rawURL string, body []byte) (*FilesystemController, *httptest.ResponseRecorder) {\n\tt.Helper()\n\tctx, rec := newTestContext(method, rawURL, body)\n\tctrl := NewFilesystemController(ctx)\n\treturn ctrl, rec\n}\n\nfunc TestFilesystemControllerGetFilesInfo(t *testing.T) {\n\ttmpDir := t.TempDir()\n\ttarget := filepath.Join(tmpDir, \"foo.txt\")\n\trequire.NoError(t, os.WriteFile(target, []byte(\"demo\"), 0o644))\n\n\tquery := fmt.Sprintf(\"/files/info?path=%s\", url.QueryEscape(target))\n\tctrl, rec := newFilesystemController(t, http.MethodGet, query, nil)\n\n\tctrl.GetFilesInfo()\n\n\trequire.Equal(t, http.StatusOK, rec.Code)\n\tvar resp map[string]model.FileInfo\n\trequire.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))\n\tinfo, ok := resp[target]\n\trequire.True(t, ok, \"response missing entry for %s\", target)\n\trequire.NotEmpty(t, info.Path)\n\trequire.NotZero(t, info.Size)\n}\n\nfunc TestFilesystemControllerSearchFiles(t *testing.T) {\n\ttmpDir := t.TempDir()\n\ta := filepath.Join(tmpDir, \"alpha.txt\")\n\tb := filepath.Join(tmpDir, \"beta.log\")\n\trequire.NoError(t, os.WriteFile(a, []byte(\"alpha\"), 0o644))\n\trequire.NoError(t, os.WriteFile(b, []byte(\"beta\"), 0o644))\n\n\trawURL := fmt.Sprintf(\"/files/search?path=%s&pattern=%s\", url.QueryEscape(tmpDir), url.QueryEscape(\"*.txt\"))\n\tctrl, rec := newFilesystemController(t, http.MethodGet, rawURL, nil)\n\n\tctrl.SearchFiles()\n\n\trequire.Equal(t, http.StatusOK, rec.Code)\n\tvar files []model.FileInfo\n\trequire.NoError(t, json.Unmarshal(rec.Body.Bytes(), &files))\n\trequire.Len(t, files, 1)\n\trequire.Equal(t, a, files[0].Path)\n}\n\nfunc TestFilesystemControllerReplaceContent(t *testing.T) {\n\ttmpDir := t.TempDir()\n\ttarget := filepath.Join(tmpDir, \"content.txt\")\n\trequire.NoError(t, os.WriteFile(target, []byte(\"hello world\"), 0o644))\n\n\tbody, err := json.Marshal(map[string]model.ReplaceFileContentItem{\n\t\ttarget: {\n\t\t\tOld: \"world\",\n\t\t\tNew: \"universe\",\n\t\t},\n\t})\n\trequire.NoError(t, err)\n\n\tctrl, rec := newFilesystemController(t, http.MethodPost, \"/files/replace\", body)\n\n\tctrl.ReplaceContent()\n\n\trequire.Equal(t, http.StatusOK, rec.Code)\n\tdata, err := os.ReadFile(target)\n\trequire.NoError(t, err)\n\trequire.Equal(t, \"hello universe\", string(data))\n}\n\nfunc TestFilesystemControllerSearchFilesHandlesAbsentDir(t *testing.T) {\n\trawURL := \"/files/search?path=/not/exists\"\n\tctrl, rec := newFilesystemController(t, http.MethodGet, rawURL, nil)\n\n\tctrl.SearchFiles()\n\n\trequire.Equal(t, http.StatusNotFound, rec.Code)\n}\n\nfunc TestReplaceContentFailsUnknownFile(t *testing.T) {\n\tpayload, _ := json.Marshal(map[string]model.ReplaceFileContentItem{\n\t\tfilepath.Join(t.TempDir(), \"missing.txt\"): {\n\t\t\tOld: \"old\",\n\t\t\tNew: \"new\",\n\t\t},\n\t})\n\tctrl, rec := newFilesystemController(t, http.MethodPost, \"/files/replace\", payload)\n\n\tctrl.ReplaceContent()\n\n\trequire.Contains(t, []int{http.StatusNotFound, http.StatusInternalServerError}, rec.Code, \"expected failure status\")\n}\n\nfunc TestFormatContentDisposition(t *testing.T) {\n\ttests := []struct {\n\t\tname string\n\t\tfilename string\n\t\twant string\n\t}{\n\t\t{\n\t\t\tname: \"ASCII filename\",\n\t\t\tfilename: \"test.txt\",\n\t\t\twant: \"attachment; filename=\\\"test.txt\\\"\",\n\t\t},\n\t\t{\n\t\t\tname: \"Chinese filename\",\n\t\t\tfilename: \"ๆต‹่ฏ•ๆ–‡ไปถ.txt\",\n\t\t\twant: \"attachment; filename=\\\"%E6%B5%8B%E8%AF%95%E6%96%87%E4%BB%B6.txt\\\"; filename*=UTF-8''%E6%B5%8B%E8%AF%95%E6%96%87%E4%BB%B6.txt\",\n\t\t},\n\t\t{\n\t\t\tname: \"Japanese filename\",\n\t\t\tfilename: \"ใƒ†ใ‚นใƒˆ.txt\",\n\t\t\twant: \"attachment; filename=\\\"%E3%83%86%E3%82%B9%E3%83%88.txt\\\"; filename*=UTF-8''%E3%83%86%E3%82%B9%E3%83%88.txt\",\n\t\t},\n\t\t{\n\t\t\tname: \"Special characters in filename\",\n\t\t\tfilename: \"file with spaces.txt\",\n\t\t\twant: \"attachment; filename=\\\"file with spaces.txt\\\"\",\n\t\t},\n\t\t{\n\t\t\tname: \"Mixed ASCII and non-ASCII\",\n\t\t\tfilename: \"report-ๆŠฅๅ‘Š.pdf\",\n\t\t\twant: \"attachment; filename=\\\"report-%E6%8A%A5%E5%91%8A.pdf\\\"; filename*=UTF-8''report-%E6%8A%A5%E5%91%8A.pdf\",\n\t\t},\n\t}\n\n\tfor _, tt := range tests {\n\t\tt.Run(tt.name, func(t *testing.T) {\n\t\t\tgot := formatContentDisposition(tt.filename)\n\t\t\trequire.Equal(t, tt.want, got)\n\t\t})\n\t}\n}\n" }, { "path": "components/execd/pkg/web/controller/filesystem_upload.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"path/filepath\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\n// UploadFile uploads files with metadata to specified paths\nfunc (c *FilesystemController) UploadFile() {\n\tform, err := c.ctx.MultipartForm()\n\tif err != nil || form == nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidFile,\n\t\t\t\"multipart form is empty\",\n\t\t)\n\t\treturn\n\t}\n\n\tmetadataParts := form.File[\"metadata\"]\n\tfileParts := form.File[\"file\"]\n\n\tif len(metadataParts) == 0 {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidFileMetadata,\n\t\t\t\"metadata file is missing\",\n\t\t)\n\t\treturn\n\t}\n\n\tif len(fileParts) == 0 {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidFileContent,\n\t\t\t\"file is missing\",\n\t\t)\n\t\treturn\n\t}\n\n\tif len(metadataParts) != len(fileParts) {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidFile,\n\t\t\tfmt.Sprintf(\"metadata and file count mismatch: %d vs %d\", len(metadataParts), len(fileParts)),\n\t\t)\n\t\treturn\n\t}\n\n\tfor i := range metadataParts {\n\t\tmetadataHeader := metadataParts[i]\n\t\tmetadataFile, err := metadataHeader.Open()\n\t\tif err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusBadRequest,\n\t\t\t\tmodel.ErrorCodeInvalidFileMetadata,\n\t\t\t\tfmt.Sprintf(\"error opening metadata file. %v\", err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\n\t\tmetaBytes, err := io.ReadAll(metadataFile)\n\t\tmetadataFile.Close()\n\t\tif err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusBadRequest,\n\t\t\t\tmodel.ErrorCodeInvalidFileMetadata,\n\t\t\t\tfmt.Sprintf(\"error reading metadata content. %v\", err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\n\t\tvar meta model.FileMetadata\n\t\tif err := json.Unmarshal(metaBytes, &meta); err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusBadRequest,\n\t\t\t\tmodel.ErrorCodeInvalidFileMetadata,\n\t\t\t\tfmt.Sprintf(\"invalid metadata format. %v\", err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\n\t\ttargetPath := meta.Path\n\t\tif targetPath == \"\" {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusBadRequest,\n\t\t\t\tmodel.ErrorCodeInvalidFileMetadata,\n\t\t\t\t\"metadata path is empty\",\n\t\t\t)\n\t\t\treturn\n\t\t}\n\n\t\ttargetDir := filepath.Dir(targetPath)\n\t\tif err := os.MkdirAll(targetDir, os.ModePerm); err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error creating target directory %s. %v\", targetDir, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\n\t\tfileHeader := fileParts[i]\n\t\tfile, err := fileHeader.Open()\n\t\tif err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error opening file %s. %v\", fileHeader.Filename, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\n\t\tdst, err := os.OpenFile(targetPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, os.ModePerm)\n\t\tif err != nil {\n\t\t\tfile.Close()\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error opening destination file %s. %v\", targetPath, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\n\t\tif _, err := io.Copy(dst, file); err != nil {\n\t\t\tdst.Close()\n\t\t\tfile.Close()\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error copying file %s. %v\", targetPath, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\n\t\tif err := dst.Sync(); err != nil {\n\t\t\tlog.Error(\"failed to sync target file: %v\", err)\n\t\t}\n\t\tif err := dst.Close(); err != nil {\n\t\t\tlog.Error(\"failed to close target file: %v\", err)\n\t\t}\n\t\tfile.Close()\n\n\t\tif err := ChmodFile(targetPath, meta.Permission); err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error chmoding file %s. %v\", targetPath, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n" }, { "path": "components/execd/pkg/web/controller/filesystem_windows.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build windows\n// +build windows\n\npackage controller\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"strconv\"\n\t\"strings\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/util/glob\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\n// FilesystemController handles file system operations.\ntype FilesystemController struct {\n\t*basicController\n}\n\nfunc NewFilesystemController(ctx *gin.Context) *FilesystemController {\n\treturn &FilesystemController{basicController: newBasicController(ctx)}\n}\n\nfunc (c *FilesystemController) handleFileError(err error) {\n\tif os.IsNotExist(err) {\n\t\tc.RespondError(\n\t\t\thttp.StatusNotFound,\n\t\t\tmodel.ErrorCodeFileNotFound,\n\t\t\tfmt.Sprintf(\"file not found. %v\", err),\n\t\t)\n\t} else {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error accessing file: %v\", err),\n\t\t)\n\t}\n}\n\n// GetFilesInfo retrieves metadata for specified file paths\nfunc (c *FilesystemController) GetFilesInfo() {\n\tpaths := c.ctx.QueryArray(\"path\")\n\tif len(paths) == 0 {\n\t\tc.RespondSuccess(make(map[string]model.FileInfo))\n\t\treturn\n\t}\n\n\tresp := make(map[string]model.FileInfo)\n\tfor _, filePath := range paths {\n\t\tfileInfo, err := GetFileInfo(filePath)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t\tresp[filePath] = fileInfo\n\t}\n\n\tc.RespondSuccess(resp)\n}\n\n// RemoveFiles deletes specified files\nfunc (c *FilesystemController) RemoveFiles() {\n\tpaths := c.ctx.QueryArray(\"path\")\n\tfor _, filePath := range paths {\n\t\tif err := DeleteFile(filePath); err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error removing file %s. %v\", filePath, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// ChmodFiles changes file permissions for specified files\nfunc (c *FilesystemController) ChmodFiles() {\n\tvar request map[string]model.Permission\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tfor file, item := range request {\n\t\terr := ChmodFile(file, item)\n\t\tif err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error changing permissions for %s. %v\", file, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// RenameFiles renames or moves files to new paths\nfunc (c *FilesystemController) RenameFiles() {\n\tvar request []model.RenameFileItem\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tfor _, renameItem := range request {\n\t\tif err := RenameFile(renameItem); err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// MakeDirs creates directories with specified permissions\nfunc (c *FilesystemController) MakeDirs() {\n\tvar request map[string]model.Permission\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tfor dir, perm := range request {\n\t\tif err := MakeDir(dir, perm); err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// RemoveDirs recursively removes directories\nfunc (c *FilesystemController) RemoveDirs() {\n\tpaths := c.ctx.QueryArray(\"path\")\n\tfor _, dir := range paths {\n\t\tif err := os.RemoveAll(dir); err != nil {\n\t\t\tc.RespondError(\n\t\t\t\thttp.StatusInternalServerError,\n\t\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\t\tfmt.Sprintf(\"error removing directory %s. %v\", dir, err),\n\t\t\t)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n\n// SearchFiles searches for files matching a pattern in a directory\nfunc (c *FilesystemController) SearchFiles() {\n\tpath := c.ctx.Query(\"path\")\n\tif path == \"\" {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeMissingQuery,\n\t\t\t\"missing query parameter 'path'\",\n\t\t)\n\t\treturn\n\t}\n\n\tpath, err := filepath.Abs(path)\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error converting path %s to absolute. %v\", path, err),\n\t\t)\n\t\treturn\n\t}\n\n\t_, err = os.Stat(path)\n\tif err != nil {\n\t\tc.handleFileError(err)\n\t\treturn\n\t}\n\n\tpattern := c.ctx.Query(\"pattern\")\n\tif pattern == \"\" {\n\t\tpattern = \"**\"\n\t}\n\n\tfiles := make([]model.FileInfo, 0, 16)\n\terr = filepath.Walk(path, func(filePath string, info os.FileInfo, err error) error {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn nil\n\t\t}\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"error accessing path %s: %w\", filePath, err)\n\t\t}\n\t\tif info.IsDir() {\n\t\t\treturn nil\n\t\t}\n\n\t\tmatch, err := glob.PathMatch(pattern, info.Name())\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"invalid pattern %s: %w\", pattern, err)\n\t\t}\n\n\t\tif match {\n\t\t\tfiles = append(files, model.FileInfo{\n\t\t\t\tPath: filePath,\n\t\t\t\tSize: info.Size(),\n\t\t\t\tModifiedAt: info.ModTime(),\n\t\t\t\tCreatedAt: getFileCreateTime(info),\n\t\t\t\tPermission: model.Permission{\n\t\t\t\t\tOwner: \"\",\n\t\t\t\t\tGroup: \"\",\n\t\t\t\t\tMode: func() int {\n\t\t\t\t\t\tmode := strconv.FormatInt(int64(info.Mode().Perm()), 8)\n\t\t\t\t\t\ti, _ := strconv.Atoi(mode)\n\t\t\t\t\t\treturn i\n\t\t\t\t\t}(),\n\t\t\t\t},\n\t\t\t})\n\t\t}\n\n\t\treturn nil\n\t})\n\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error searching files. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tc.RespondSuccess(files)\n}\n\n// ReplaceContent replaces text content in specified files\nfunc (c *FilesystemController) ReplaceContent() {\n\tvar request map[string]model.ReplaceFileContentItem\n\tif err := c.bindJSON(&request); err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusBadRequest,\n\t\t\tmodel.ErrorCodeInvalidRequest,\n\t\t\tfmt.Sprintf(\"error parsing request, MAYBE invalid body format. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tfor file, item := range request {\n\t\tfile, err := filepath.Abs(file)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\n\t\tif _, err = os.Stat(file); err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\n\t\tcontent, err := os.ReadFile(file)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\n\t\tfileInfo, err := os.Stat(file)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t\tmode := fileInfo.Mode()\n\n\t\tnewContent := strings.ReplaceAll(string(content), item.Old, item.New)\n\n\t\terr = os.WriteFile(file, []byte(newContent), mode)\n\t\tif err != nil {\n\t\t\tc.handleFileError(err)\n\t\t\treturn\n\t\t}\n\t}\n\n\tc.RespondSuccess(nil)\n}\n" }, { "path": "components/execd/pkg/web/controller/metric.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"runtime\"\n\t\"time\"\n\n\t\"github.com/gin-gonic/gin\"\n\t\"github.com/shirou/gopsutil/cpu\"\n\t\"github.com/shirou/gopsutil/mem\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\n// MetricController handles system metrics requests\ntype MetricController struct {\n\t*basicController\n}\n\nfunc NewMetricController(ctx *gin.Context) *MetricController {\n\treturn &MetricController{basicController: newBasicController(ctx)}\n}\n\n// GetMetrics returns current system metrics\nfunc (c *MetricController) GetMetrics() {\n\tmetrics, err := c.readMetrics()\n\tif err != nil {\n\t\tc.RespondError(\n\t\t\thttp.StatusInternalServerError,\n\t\t\tmodel.ErrorCodeRuntimeError,\n\t\t\tfmt.Sprintf(\"error reading runtime metrics. %v\", err),\n\t\t)\n\t\treturn\n\t}\n\n\tc.RespondSuccess(metrics)\n}\n\n// WatchMetrics streams system metrics via SSE\nfunc (c *MetricController) WatchMetrics() {\n\tc.setupSSEResponse()\n\n\tfor {\n\t\tselect {\n\t\tcase <-c.ctx.Request.Context().Done():\n\t\t\treturn\n\t\tcase <-time.After(time.Second * 1):\n\t\t\tfunc() {\n\t\t\t\tif flusher, ok := c.ctx.Writer.(http.Flusher); ok {\n\t\t\t\t\tdefer flusher.Flush()\n\t\t\t\t}\n\t\t\t\tmetrics, err := c.readMetrics()\n\t\t\t\tif err != nil {\n\t\t\t\t\tmsg, _ := json.Marshal(map[string]string{ //nolint:errchkjson\n\t\t\t\t\t\t\"error\": err.Error(),\n\t\t\t\t\t})\n\t\t\t\t\t_, err = c.ctx.Writer.Write(append(msg, '\\n'))\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\tlog.Error(\"WatchMetrics write data %s error: %v\", string(msg), err)\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tmsg, _ := json.Marshal(metrics) //nolint:errchkjson\n\t\t\t\t\t_, err = c.ctx.Writer.Write(append(msg, '\\n'))\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\tlog.Error(\"WatchMetrics write data %s error: %v\", string(msg), err)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}()\n\t\t}\n\t}\n}\n\n// readMetrics collects current CPU and memory metrics\nfunc (c *MetricController) readMetrics() (*model.Metrics, error) {\n\tmetric := model.NewMetrics()\n\n\tmetric.CpuCount = float64(runtime.GOMAXPROCS(-1))\n\tcpuPercent, err := cpu.Percent(time.Second, false)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get CPU percent: %w\", err)\n\t}\n\tif len(cpuPercent) > 0 {\n\t\tmetric.CpuUsedPct = cpuPercent[0]\n\t}\n\n\tvmStat, err := mem.VirtualMemory()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get memory info: %w\", err)\n\t}\n\tmetric.MemTotalMiB = float64(vmStat.Total) / 1024 / 1024\n\tmetric.MemUsedMiB = float64(vmStat.Used) / 1024 / 1024\n\n\treturn metric, nil\n}\n" }, { "path": "components/execd/pkg/web/controller/metric_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/stretchr/testify/assert\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\nfunc setupMetricController(method, path string) (*MetricController, *httptest.ResponseRecorder) {\n\tctx, w := newTestContext(method, path, nil)\n\tctrl := NewMetricController(ctx)\n\treturn ctrl, w\n}\n\n// TestReadMetrics exercises readMetrics end-to-end.\nfunc TestReadMetrics(t *testing.T) {\n\tctrl := &MetricController{}\n\n\tmetrics, err := ctrl.readMetrics()\n\n\tassert.NoError(t, err)\n\tassert.NotNil(t, metrics)\n\n\t// Validate CPU count\n\tassert.Greater(t, metrics.CpuCount, 0.0)\n\n\t// Validate CPU utilization\n\tassert.GreaterOrEqual(t, metrics.CpuUsedPct, 0.0)\n\tassert.Less(t, metrics.CpuUsedPct, 100.1) // CPU usage should be under 100% with small float tolerance\n\n\t// Validate memory information\n\tassert.Greater(t, metrics.MemTotalMiB, 0.0)\n\tassert.GreaterOrEqual(t, metrics.MemUsedMiB, 0.0)\n\tassert.LessOrEqual(t, metrics.MemUsedMiB, metrics.MemTotalMiB) // Used memory should not exceed total\n\n\t// Validate timestamps\n\tcurrentTime := time.Now().UnixMilli()\n\toneMinuteAgo := currentTime - 60*1000\n\tassert.GreaterOrEqual(t, metrics.Timestamp, oneMinuteAgo) // Should be within the last minute\n\tassert.LessOrEqual(t, metrics.Timestamp, currentTime) // Should not be in the future\n}\n\n// TestGetMetricsEndpoint covers the happy path.\nfunc TestGetMetricsEndpoint(t *testing.T) {\n\tctrl, w := setupMetricController(\"GET\", \"/api/metrics\")\n\n\tctrl.GetMetrics()\n\n\tassert.Equal(t, http.StatusOK, w.Code)\n\n\tvar metrics model.Metrics\n\terr := json.Unmarshal(w.Body.Bytes(), &metrics)\n\tassert.NoError(t, err)\n\n\tassert.Greater(t, metrics.CpuCount, 0.0)\n\tassert.GreaterOrEqual(t, metrics.CpuUsedPct, 0.0)\n\tassert.Greater(t, metrics.MemTotalMiB, 0.0)\n\tassert.GreaterOrEqual(t, metrics.MemUsedMiB, 0.0)\n\tassert.NotZero(t, metrics.Timestamp)\n}\n\n// TestWatchMetricsHeaders verifies SSE header defaults.\nfunc TestWatchMetricsHeaders(t *testing.T) {\n\tctrl, w := setupMetricController(\"GET\", \"/api/watch-metrics\")\n\n\tctrl.setupSSEResponse()\n\n\tcontentType := w.Header().Get(\"Content-Type\")\n\tassert.Equal(t, \"text/event-stream\", contentType)\n\n\tcacheControl := w.Header().Get(\"Cache-Control\")\n\tassert.Equal(t, \"no-cache\", cacheControl)\n\n\tconnection := w.Header().Get(\"Connection\")\n\tassert.Equal(t, \"keep-alive\", connection)\n\n\tbuffering := w.Header().Get(\"X-Accel-Buffering\")\n\tassert.Equal(t, \"no\", buffering)\n}\n\n// TestMetricSerialization ensures metrics marshal and unmarshal cleanly.\nfunc TestMetricSerialization(t *testing.T) {\n\tmetrics := &model.Metrics{\n\t\tCpuCount: 4,\n\t\tCpuUsedPct: 25.5,\n\t\tMemTotalMiB: 8192,\n\t\tMemUsedMiB: 4096,\n\t\tTimestamp: time.Now().UnixMilli(),\n\t}\n\n\tdata, err := json.Marshal(metrics)\n\tassert.NoError(t, err)\n\n\tvar decodedMetrics model.Metrics\n\terr = json.Unmarshal(data, &decodedMetrics)\n\tassert.NoError(t, err)\n\tassert.Equal(t, metrics.CpuCount, decodedMetrics.CpuCount)\n\tassert.Equal(t, metrics.CpuUsedPct, decodedMetrics.CpuUsedPct)\n\tassert.Equal(t, metrics.MemTotalMiB, decodedMetrics.MemTotalMiB)\n\tassert.Equal(t, metrics.MemUsedMiB, decodedMetrics.MemUsedMiB)\n\tassert.Equal(t, metrics.Timestamp, decodedMetrics.Timestamp)\n\n\terrorMsg := map[string]string{\"error\": \"test error\"}\n\terrorData, err := json.Marshal(errorMsg)\n\tassert.NoError(t, err)\n\n\tvar decodedError map[string]string\n\terr = json.Unmarshal(errorData, &decodedError)\n\tassert.NoError(t, err)\n\tassert.Equal(t, \"test error\", decodedError[\"error\"])\n}\n" }, { "path": "components/execd/pkg/web/controller/mock_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"bytes\"\n\t\"net/http\"\n)\n\ntype mockOutput struct {\n\tbuffer *bytes.Buffer\n\tstatusCode int\n\theader http.Header\n}\n\nfunc (m *mockOutput) Header() http.Header {\n\tif m.header == nil {\n\t\tm.header = make(http.Header)\n\t}\n\treturn m.header\n}\n\nfunc (m *mockOutput) Write(b []byte) (int, error) {\n\treturn m.buffer.Write(b)\n}\n\nfunc (m *mockOutput) WriteHeader(code int) {\n\tm.statusCode = code\n}\n\nfunc (m *mockOutput) Status() int {\n\treturn m.statusCode\n}\n\nfunc (m *mockOutput) Body() []byte {\n\treturn m.buffer.Bytes()\n}\n" }, { "path": "components/execd/pkg/web/controller/ping.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport \"github.com/gin-gonic/gin\"\n\n// MainController handles basic server operations.\ntype MainController struct {\n\t*basicController\n}\n\nfunc NewMainController(ctx *gin.Context) *MainController {\n\treturn &MainController{basicController: newBasicController(ctx)}\n}\n\n// Ping checks if the server is alive.\nfunc (c *MainController) Ping() {\n\tc.RespondSuccess(nil)\n}\n\n// PingHandler is the Gin adapter.\nfunc PingHandler(ctx *gin.Context) {\n\tNewMainController(ctx).Ping()\n}\n" }, { "path": "components/execd/pkg/web/controller/sse.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"context\"\n\t\"io\"\n\t\"net/http\"\n\t\"time\"\n\n\t\"k8s.io/apimachinery/pkg/util/wait\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/runtime\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/util/safego\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\nvar sseHeaders = map[string]string{\n\t\"Content-Type\": \"text/event-stream\",\n\t\"Cache-Control\": \"no-cache\",\n\t\"Connection\": \"keep-alive\",\n\t\"X-Accel-Buffering\": \"no\",\n}\n\nfunc (c *basicController) setupSSEResponse() {\n\tfor key, value := range sseHeaders {\n\t\tc.ctx.Writer.Header().Set(key, value)\n\t}\n\tif flusher, ok := c.ctx.Writer.(http.Flusher); ok {\n\t\tflusher.Flush()\n\t}\n}\n\n// setServerEventsHandler adapts runtime callbacks to SSE events.\nfunc (c *CodeInterpretingController) setServerEventsHandler(ctx context.Context) runtime.ExecuteResultHook {\n\treturn runtime.ExecuteResultHook{\n\t\tOnExecuteInit: func(session string) {\n\t\t\tevent := model.ServerStreamEvent{\n\t\t\t\tType: model.StreamEventTypeInit,\n\t\t\t\tText: session,\n\t\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t\t}\n\t\t\tpayload := event.ToJSON()\n\t\t\tc.writeSingleEvent(\"OnExecuteInit\", payload, true, event.Summary())\n\n\t\t\tsafego.Go(func() { c.ping(ctx) })\n\t\t},\n\t\tOnExecuteResult: func(result map[string]any, count int) {\n\t\t\tvar mutated map[string]any\n\t\t\tif len(result) > 0 {\n\t\t\t\tmutated = make(map[string]any)\n\t\t\t\tfor k, v := range result {\n\t\t\t\t\tswitch k {\n\t\t\t\t\tcase \"text/plain\":\n\t\t\t\t\t\tmutated[\"text\"] = v\n\t\t\t\t\tdefault:\n\t\t\t\t\t\tmutated[k] = v\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif count > 0 {\n\t\t\t\tevent := model.ServerStreamEvent{\n\t\t\t\t\tType: model.StreamEventTypeCount,\n\t\t\t\t\tExecutionCount: count,\n\t\t\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t\t\t}\n\t\t\t\tpayload := event.ToJSON()\n\t\t\t\tc.writeSingleEvent(\"OnExecuteResult\", payload, true, event.Summary())\n\t\t\t}\n\t\t\tif len(mutated) > 0 {\n\t\t\t\tevent := model.ServerStreamEvent{\n\t\t\t\t\tType: model.StreamEventTypeResult,\n\t\t\t\t\tResults: mutated,\n\t\t\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t\t\t}\n\t\t\t\tpayload := event.ToJSON()\n\t\t\t\tc.writeSingleEvent(\"OnExecuteResult\", payload, true, event.Summary())\n\t\t\t}\n\t\t},\n\t\tOnExecuteComplete: func(executionTime time.Duration) {\n\t\t\tevent := model.ServerStreamEvent{\n\t\t\t\tType: model.StreamEventTypeComplete,\n\t\t\t\tExecutionTime: executionTime.Milliseconds(),\n\t\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t\t}\n\t\t\tpayload := event.ToJSON()\n\t\t\tc.writeSingleEvent(\"OnExecuteComplete\", payload, true, event.Summary())\n\t\t},\n\t\tOnExecuteError: func(err *execute.ErrorOutput) {\n\t\t\tif err == nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tevent := model.ServerStreamEvent{\n\t\t\t\tType: model.StreamEventTypeError,\n\t\t\t\tError: err,\n\t\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t\t}\n\t\t\tpayload := event.ToJSON()\n\t\t\tc.writeSingleEvent(\"OnExecuteError\", payload, true, event.Summary())\n\t\t},\n\t\tOnExecuteStatus: func(status string) {\n\t\t\tevent := model.ServerStreamEvent{\n\t\t\t\tType: model.StreamEventTypeStatus,\n\t\t\t\tText: status,\n\t\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t\t}\n\t\t\tpayload := event.ToJSON()\n\t\t\tc.writeSingleEvent(\"OnExecuteStatus\", payload, true, event.Summary())\n\t\t},\n\t\tOnExecuteStdout: func(text string) {\n\t\t\tif text == \"\" {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tevent := model.ServerStreamEvent{\n\t\t\t\tType: model.StreamEventTypeStdout,\n\t\t\t\tText: text,\n\t\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t\t}\n\t\t\tpayload := event.ToJSON()\n\t\t\tc.writeSingleEvent(\"OnExecuteStdout\", payload, true, event.Summary())\n\t\t},\n\t\tOnExecuteStderr: func(text string) {\n\t\t\tif text == \"\" {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tevent := model.ServerStreamEvent{\n\t\t\t\tType: model.StreamEventTypeStderr,\n\t\t\t\tText: text,\n\t\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t\t}\n\t\t\tpayload := event.ToJSON()\n\t\t\tc.writeSingleEvent(\"OnExecuteStderr\", payload, true, event.Summary())\n\t\t},\n\t}\n}\n\n// writeSingleEvent serializes one SSE frame.\nfunc (c *CodeInterpretingController) writeSingleEvent(handler string, data []byte, verbose bool, summary string) {\n\tif c == nil || c.ctx == nil || c.ctx.Writer == nil {\n\t\treturn\n\t}\n\n\tselect {\n\tcase <-c.ctx.Request.Context().Done():\n\t\tlog.Error(\"StreamEvent.%s: client disconnected\", handler)\n\t\treturn\n\tdefault:\n\t}\n\n\tc.chunkWriter.Lock()\n\tdefer c.chunkWriter.Unlock()\n\tdefer func() {\n\t\tif flusher, ok := c.ctx.Writer.(http.Flusher); ok {\n\t\t\tflusher.Flush()\n\t\t}\n\t}()\n\n\tpayload := append(data, '\\n', '\\n')\n\tn, err := c.ctx.Writer.Write(payload)\n\tif err == nil && n != len(payload) {\n\t\terr = io.ErrShortWrite\n\t}\n\n\tif err != nil {\n\t\tlog.Error(\"StreamEvent.%s write data %s error: %v\", handler, summary, err)\n\t} else {\n\t\tif verbose {\n\t\t\tlog.Info(\"StreamEvent.%s write data %s\", handler, summary)\n\t\t}\n\t}\n}\n\n// ping periodically keeps the SSE connection alive.\nfunc (c *CodeInterpretingController) ping(ctx context.Context) {\n\twait.Until(func() {\n\t\tif c.ctx.Writer == nil {\n\t\t\treturn\n\t\t}\n\t\tevent := model.ServerStreamEvent{\n\t\t\tType: model.StreamEventTypePing,\n\t\t\tText: \"pong\",\n\t\t\tTimestamp: time.Now().UnixMilli(),\n\t\t}\n\t\tpayload := event.ToJSON()\n\t\tc.writeSingleEvent(\"Ping\", payload, false, event.Summary())\n\t}, 3*time.Second, ctx.Done())\n}\n" }, { "path": "components/execd/pkg/web/controller/syscall_linux.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build linux\n// +build linux\n\npackage controller\n\nimport (\n\t\"os\"\n\t\"syscall\"\n\t\"time\"\n)\n\nfunc getFileCreateTime(fileInfo os.FileInfo) time.Time {\n\tstat, ok := fileInfo.Sys().(*syscall.Stat_t)\n\tif !ok || stat == nil {\n\t\treturn fileInfo.ModTime()\n\t}\n\n\treturn time.Unix(stat.Ctim.Sec, stat.Ctim.Nsec)\n}\n" }, { "path": "components/execd/pkg/web/controller/syscall_others.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build !linux\n// +build !linux\n\npackage controller\n\nimport (\n\t\"os\"\n\t\"time\"\n)\n\nfunc getFileCreateTime(_ os.FileInfo) time.Time {\n\treturn time.Now()\n}\n" }, { "path": "components/execd/pkg/web/controller/test_helpers.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"bytes\"\n\t\"net/http/httptest\"\n\n\t\"github.com/gin-gonic/gin\"\n)\n\n// nolint:unused\nfunc newTestContext(method, path string, body []byte) (*gin.Context, *httptest.ResponseRecorder) {\n\tgin.SetMode(gin.TestMode)\n\tw := httptest.NewRecorder()\n\tctx, _ := gin.CreateTestContext(w)\n\treq := httptest.NewRequest(method, path, bytes.NewReader(body))\n\tctx.Request = req\n\treturn ctx, w\n}\n" }, { "path": "components/execd/pkg/web/controller/utils.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build !windows\n// +build !windows\n\npackage controller\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"os/user\"\n\t\"path/filepath\"\n\t\"strconv\"\n\t\"strings\"\n\t\"syscall\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\nfunc DeleteFile(filePath string) error {\n\tabsPath, err := filepath.Abs(filePath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"invalid path: %w\", err)\n\t}\n\n\tfileInfo, err := os.Stat(absPath)\n\tif err != nil {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn nil\n\t\t}\n\t\treturn err\n\t}\n\n\tif fileInfo.IsDir() {\n\t\treturn fmt.Errorf(\"path is a directory: %s\", filePath)\n\t}\n\n\tif err := os.Remove(absPath); err != nil {\n\t\treturn fmt.Errorf(\"failed to remove file: %w\", err)\n\t}\n\n\treturn nil\n}\n\nfunc ChmodFile(file string, perms model.Permission) error {\n\tabs, err := filepath.Abs(file)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif perms.Mode != 0 {\n\t\tmode, err := strconv.ParseUint(strconv.Itoa(perms.Mode), 8, 32)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\terr = os.Chmod(abs, os.FileMode(mode))\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn SetFileOwnership(abs, perms.Owner, perms.Group)\n}\n\nfunc SetFileOwnership(absPath string, owner string, group string) error {\n\tuid := -1\n\tif owner != \"\" {\n\t\tuserInfo, err := user.Lookup(owner)\n\t\tif err != nil {\n\t\t\tlog.Warning(\"Failed to lookup user %s: %v\", owner, err)\n\t\t} else {\n\t\t\tuid, err = strconv.Atoi(userInfo.Uid)\n\t\t\tif err != nil {\n\t\t\t\tlog.Warning(\"Failed to convert uid for user %s: %v\", owner, err)\n\t\t\t\tuid = -1\n\t\t\t}\n\t\t}\n\t}\n\n\tgid := -1\n\tif group != \"\" {\n\t\tgroupInfo, err := user.LookupGroup(group)\n\t\tif err != nil {\n\t\t\tlog.Warning(\"Failed to lookup group %s: %v\", group, err)\n\t\t} else {\n\t\t\tgid, err = strconv.Atoi(groupInfo.Gid)\n\t\t\tif err != nil {\n\t\t\t\tlog.Warning(\"Failed to convert gid for group %s: %v\", group, err)\n\t\t\t\tgid = -1\n\t\t\t}\n\t\t}\n\t}\n\n\tif uid == -1 && gid == -1 {\n\t\tuid = os.Getuid()\n\t\tgid = os.Getgid()\n\t}\n\n\tif err := os.Chown(absPath, uid, gid); err != nil {\n\t\treturn fmt.Errorf(\"failed to set owner/group for %s: %w\", absPath, err)\n\t}\n\n\treturn nil\n}\n\nfunc RenameFile(item model.RenameFileItem) error {\n\tsrcPath, err := filepath.Abs(item.Src)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"invalid source path: %w\", err)\n\t}\n\n\tdstPath, err := filepath.Abs(item.Dest)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"invalid destination path: %w\", err)\n\t}\n\n\tif _, err := os.Stat(srcPath); os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"source path not found: %s\", item.Src)\n\t}\n\n\tdstDir := filepath.Dir(dstPath)\n\n\tif err := os.MkdirAll(dstDir, 0755); err != nil {\n\t\treturn fmt.Errorf(\"failed to create destination directory: %w\", err)\n\t}\n\n\tif _, err := os.Stat(dstPath); err == nil {\n\t\treturn fmt.Errorf(\"destination path already exists: %s\", item.Dest)\n\t}\n\n\tif err := os.Rename(srcPath, dstPath); err != nil {\n\t\treturn fmt.Errorf(\"failed to rename file: %w\", err)\n\t}\n\n\treturn nil\n}\n\nfunc MakeDir(dir string, perm model.Permission) error {\n\tabs, err := filepath.Abs(dir)\n\tif err != nil {\n\t\treturn err\n\t}\n\terr = os.MkdirAll(abs, os.ModePerm)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\treturn ChmodFile(abs, perm)\n}\n\nfunc GetFileInfo(filePath string) (model.FileInfo, error) {\n\tabsPath, err := filepath.Abs(filePath)\n\tif err != nil {\n\t\treturn model.FileInfo{}, fmt.Errorf(\"invalid path %s: %w\", filePath, err)\n\t}\n\n\tfileInfo, err := os.Stat(absPath)\n\tif err != nil {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn model.FileInfo{}, fmt.Errorf(\"file not found: %s\", filePath)\n\t\t}\n\t\treturn model.FileInfo{}, fmt.Errorf(\"error accessing file %s: %w\", filePath, err)\n\t}\n\n\tstat := fileInfo.Sys().(*syscall.Stat_t)\n\n\towner := strconv.FormatUint(uint64(stat.Uid), 10)\n\tif ownerUser, err := user.LookupId(owner); err == nil {\n\t\towner = ownerUser.Username\n\t}\n\n\tgroup := strconv.FormatUint(uint64(stat.Gid), 10)\n\tif groupInfo, err := user.LookupGroupId(group); err == nil {\n\t\tgroup = groupInfo.Name\n\t}\n\n\tmode := strconv.FormatInt(int64(fileInfo.Mode().Perm()), 8)\n\n\treturn model.FileInfo{\n\t\tPath: absPath,\n\t\tSize: fileInfo.Size(),\n\t\tModifiedAt: fileInfo.ModTime(),\n\t\tCreatedAt: getFileCreateTime(fileInfo),\n\t\tPermission: model.Permission{\n\t\t\tOwner: owner,\n\t\t\tGroup: group,\n\t\t\tMode: func() int { i, _ := strconv.Atoi(mode); return i }(),\n\t\t},\n\t}, nil\n}\n\nfunc SearchFileMetadata(metadata map[string]model.FileMetadata, filePath string) (string, model.FileMetadata, bool) {\n\tbase := filepath.Base(filePath)\n\tfor path, info := range metadata {\n\t\tif filepath.Base(path) == base {\n\t\t\treturn path, info, true\n\t\t}\n\t}\n\n\treturn \"\", model.FileMetadata{}, false\n}\n\ntype httpRange struct {\n\tstart, length int64\n}\n\nfunc ParseRange(s string, size int64) ([]httpRange, error) {\n\tif !strings.HasPrefix(s, \"bytes=\") {\n\t\treturn nil, errors.New(\"invalid range\")\n\t}\n\n\tranges := strings.Split(s[6:], \",\")\n\tresult := make([]httpRange, 0, len(ranges))\n\n\tfor _, ra := range ranges {\n\t\tra = strings.TrimSpace(ra)\n\t\tif ra == \"\" {\n\t\t\tcontinue\n\t\t}\n\t\ti := strings.Index(ra, \"-\")\n\t\tif i < 0 {\n\t\t\treturn nil, errors.New(\"invalid range\")\n\t\t}\n\t\tstart, end := strings.TrimSpace(ra[:i]), strings.TrimSpace(ra[i+1:])\n\t\tvar r httpRange\n\n\t\tif start == \"\" {\n\t\t\t// suffix-length\n\t\t\tn, err := strconv.ParseInt(end, 10, 64)\n\t\t\tif err != nil || n < 0 {\n\t\t\t\treturn nil, errors.New(\"invalid range\")\n\t\t\t}\n\t\t\tif n > size {\n\t\t\t\tn = size\n\t\t\t}\n\t\t\tr.start = size - n\n\t\t\tr.length = size - r.start\n\t\t} else {\n\t\t\t// start-end\n\t\t\ti, err := strconv.ParseInt(start, 10, 64)\n\t\t\tif err != nil || i < 0 {\n\t\t\t\treturn nil, errors.New(\"invalid range\")\n\t\t\t}\n\t\t\tif end == \"\" {\n\t\t\t\t// start-\n\t\t\t\tr.start = i\n\t\t\t\tr.length = size - i\n\t\t\t} else {\n\t\t\t\t// start-end\n\t\t\t\tj, err := strconv.ParseInt(end, 10, 64)\n\t\t\t\tif err != nil || j < i {\n\t\t\t\t\treturn nil, errors.New(\"invalid range\")\n\t\t\t\t}\n\t\t\t\tr.start = i\n\t\t\t\tr.length = j - i + 1\n\t\t\t}\n\t\t}\n\t\tif r.start >= size {\n\t\t\tcontinue\n\t\t}\n\t\tif r.start+r.length > size {\n\t\t\tr.length = size - r.start\n\t\t}\n\t\tresult = append(result, r)\n\t}\n\treturn result, nil\n}\n" }, { "path": "components/execd/pkg/web/controller/utils_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage controller\n\nimport (\n\t\"os\"\n\t\"path/filepath\"\n\t\"reflect\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestDeleteFile(t *testing.T) {\n\ttmp := t.TempDir()\n\tfile := filepath.Join(tmp, \"sample.txt\")\n\trequire.NoError(t, os.WriteFile(file, []byte(\"hello\"), 0o644))\n\n\trequire.NoError(t, DeleteFile(file))\n\t_, err := os.Stat(file)\n\trequire.True(t, os.IsNotExist(err), \"expected file removed, got err=%v\", err)\n\n\t// removing a non-existent file should be a no-op\n\trequire.NoError(t, DeleteFile(file), \"expected no error deleting missing file\")\n}\n\nfunc TestRenameFile(t *testing.T) {\n\ttmp := t.TempDir()\n\tsrc := filepath.Join(tmp, \"src.txt\")\n\trequire.NoError(t, os.WriteFile(src, []byte(\"data\"), 0o644))\n\n\tdst := filepath.Join(tmp, \"nested\", \"renamed.txt\")\n\trequire.NoError(t, RenameFile(model.RenameFileItem{Src: src, Dest: dst}))\n\n\t_, err := os.Stat(dst)\n\trequire.NoError(t, err)\n\t_, err = os.Stat(src)\n\trequire.True(t, os.IsNotExist(err), \"expected source removed, got err=%v\", err)\n\n\t// destination exists -> expect error\n\trequire.NoError(t, os.WriteFile(src, []byte(\"data\"), 0o644))\n\trequire.Error(t, RenameFile(model.RenameFileItem{Src: src, Dest: dst}), \"expected error when destination already exists\")\n}\n\nfunc TestSearchFileMetadata(t *testing.T) {\n\tmetadata := map[string]model.FileMetadata{\n\t\t\"/tmp/a/notes.txt\": {Path: \"/tmp/a/notes.txt\"},\n\t\t\"/tmp/b/readme.md\": {Path: \"/tmp/b/readme.md\"},\n\t}\n\n\tpath, info, ok := SearchFileMetadata(metadata, \"/any/notes.txt\")\n\trequire.True(t, ok, \"expected metadata entry\")\n\trequire.Equal(t, \"/tmp/a/notes.txt\", path)\n\trequire.Equal(t, \"/tmp/a/notes.txt\", info.Path)\n\n\t_, _, ok = SearchFileMetadata(metadata, \"/foo/unknown.txt\")\n\trequire.False(t, ok, \"expected no match\")\n}\n\nfunc TestParseRange(t *testing.T) {\n\ttests := []struct {\n\t\tname string\n\t\theader string\n\t\tsize int64\n\t\twant []httpRange\n\t\texpectErr bool\n\t}{\n\t\t{\n\t\t\tname: \"start-end\",\n\t\t\theader: \"bytes=0-9\",\n\t\t\tsize: 20,\n\t\t\twant: []httpRange{{start: 0, length: 10}},\n\t\t},\n\t\t{\n\t\t\tname: \"suffix\",\n\t\t\theader: \"bytes=-5\",\n\t\t\tsize: 10,\n\t\t\twant: []httpRange{{start: 5, length: 5}},\n\t\t},\n\t\t{\n\t\t\tname: \"invalid\",\n\t\t\theader: \"bytes=foo\",\n\t\t\tsize: 10,\n\t\t\texpectErr: true,\n\t\t},\n\t}\n\n\tfor _, tt := range tests {\n\t\tt.Run(tt.name, func(t *testing.T) {\n\t\t\tgot, err := ParseRange(tt.header, tt.size)\n\t\t\tif tt.expectErr {\n\t\t\t\trequire.Error(t, err)\n\t\t\t\treturn\n\t\t\t}\n\t\t\trequire.NoError(t, err)\n\t\t\trequire.True(t, reflect.DeepEqual(got, tt.want), \"got %+v want %+v\", got, tt.want)\n\t\t})\n\t}\n}\n" }, { "path": "components/execd/pkg/web/controller/utils_windows.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\n//go:build windows\n// +build windows\n\npackage controller\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"strconv\"\n\t\"strings\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\nfunc DeleteFile(filePath string) error {\n\tabsPath, err := filepath.Abs(filePath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"invalid path: %w\", err)\n\t}\n\n\tfileInfo, err := os.Stat(absPath)\n\tif err != nil {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn nil\n\t\t}\n\t\treturn err\n\t}\n\n\tif fileInfo.IsDir() {\n\t\treturn fmt.Errorf(\"path is a directory: %s\", filePath)\n\t}\n\n\tif err := os.Remove(absPath); err != nil {\n\t\treturn fmt.Errorf(\"failed to remove file: %w\", err)\n\t}\n\n\treturn nil\n}\n\nfunc ChmodFile(file string, perms model.Permission) error {\n\tabs, err := filepath.Abs(file)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif perms.Mode != 0 {\n\t\tmode, err := strconv.ParseUint(strconv.Itoa(perms.Mode), 8, 32)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\terr = os.Chmod(abs, os.FileMode(mode))\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn SetFileOwnership(abs, perms.Owner, perms.Group)\n}\n\n// SetFileOwnership is a placeholder on Windows where POSIX ownership is not supported.\nfunc SetFileOwnership(_ string, _ string, _ string) error {\n\t// TODO: add Windows ACL support if needed.\n\treturn nil\n}\n\nfunc RenameFile(item model.RenameFileItem) error {\n\tsrcPath, err := filepath.Abs(item.Src)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"invalid source path: %w\", err)\n\t}\n\n\tdstPath, err := filepath.Abs(item.Dest)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"invalid destination path: %w\", err)\n\t}\n\n\tif _, err := os.Stat(srcPath); os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"source path not found: %s\", item.Src)\n\t}\n\n\tdstDir := filepath.Dir(dstPath)\n\n\tif err := os.MkdirAll(dstDir, 0755); err != nil {\n\t\treturn fmt.Errorf(\"failed to create destination directory: %w\", err)\n\t}\n\n\tif _, err := os.Stat(dstPath); err == nil {\n\t\treturn fmt.Errorf(\"destination path already exists: %s\", item.Dest)\n\t}\n\n\tif err := os.Rename(srcPath, dstPath); err != nil {\n\t\treturn fmt.Errorf(\"failed to rename file: %w\", err)\n\t}\n\n\treturn nil\n}\n\nfunc MakeDir(dir string, perm model.Permission) error {\n\tabs, err := filepath.Abs(dir)\n\tif err != nil {\n\t\treturn err\n\t}\n\terr = os.MkdirAll(abs, os.ModePerm)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\treturn ChmodFile(abs, perm)\n}\n\nfunc GetFileInfo(filePath string) (model.FileInfo, error) {\n\tabsPath, err := filepath.Abs(filePath)\n\tif err != nil {\n\t\treturn model.FileInfo{}, fmt.Errorf(\"invalid path %s: %w\", filePath, err)\n\t}\n\n\tfileInfo, err := os.Stat(absPath)\n\tif err != nil {\n\t\tif os.IsNotExist(err) {\n\t\t\treturn model.FileInfo{}, fmt.Errorf(\"file not found: %s\", filePath)\n\t\t}\n\t\treturn model.FileInfo{}, fmt.Errorf(\"error accessing file %s: %w\", filePath, err)\n\t}\n\n\tcreatedAt := getFileCreateTime(fileInfo)\n\tif data, ok := fileInfo.Sys().(*syscall.Win32FileAttributeData); ok && data != nil {\n\t\tcreatedAt = time.Unix(0, data.CreationTime.Nanoseconds())\n\t}\n\n\tmode := strconv.FormatInt(int64(fileInfo.Mode().Perm()), 8)\n\n\treturn model.FileInfo{\n\t\tPath: absPath,\n\t\tSize: fileInfo.Size(),\n\t\tModifiedAt: fileInfo.ModTime(),\n\t\tCreatedAt: createdAt,\n\t\tPermission: model.Permission{\n\t\t\tOwner: \"\",\n\t\t\tGroup: \"\",\n\t\t\tMode: func() int {\n\t\t\t\ti, _ := strconv.Atoi(mode)\n\t\t\t\treturn i\n\t\t\t}(),\n\t\t},\n\t}, nil\n}\n\nfunc SearchFileMetadata(metadata map[string]model.FileMetadata, filePath string) (string, model.FileMetadata, bool) {\n\tbase := filepath.Base(filePath)\n\tfor path, info := range metadata {\n\t\tif filepath.Base(path) == base {\n\t\t\treturn path, info, true\n\t\t}\n\t}\n\n\treturn \"\", model.FileMetadata{}, false\n}\n\ntype httpRange struct {\n\tstart, length int64\n}\n\nfunc ParseRange(s string, size int64) ([]httpRange, error) {\n\tif !strings.HasPrefix(s, \"bytes=\") {\n\t\treturn nil, errors.New(\"invalid range\")\n\t}\n\n\tranges := strings.Split(s[6:], \",\")\n\tresult := make([]httpRange, 0, len(ranges))\n\n\tfor _, ra := range ranges {\n\t\tra = strings.TrimSpace(ra)\n\t\tif ra == \"\" {\n\t\t\tcontinue\n\t\t}\n\t\ti := strings.Index(ra, \"-\")\n\t\tif i < 0 {\n\t\t\treturn nil, errors.New(\"invalid range\")\n\t\t}\n\t\tstart, end := strings.TrimSpace(ra[:i]), strings.TrimSpace(ra[i+1:])\n\t\tvar r httpRange\n\n\t\tif start == \"\" {\n\t\t\t// suffix-length\n\t\t\tn, err := strconv.ParseInt(end, 10, 64)\n\t\t\tif err != nil || n < 0 {\n\t\t\t\treturn nil, errors.New(\"invalid range\")\n\t\t\t}\n\t\t\tif n > size {\n\t\t\t\tn = size\n\t\t\t}\n\t\t\tr.start = size - n\n\t\t\tr.length = size - r.start\n\t\t} else {\n\t\t\t// start-end\n\t\t\ti, err := strconv.ParseInt(start, 10, 64)\n\t\t\tif err != nil || i < 0 {\n\t\t\t\treturn nil, errors.New(\"invalid range\")\n\t\t\t}\n\t\t\tif end == \"\" {\n\t\t\t\t// start-\n\t\t\t\tr.start = i\n\t\t\t\tr.length = size - i\n\t\t\t} else {\n\t\t\t\t// start-end\n\t\t\t\tj, err := strconv.ParseInt(end, 10, 64)\n\t\t\t\tif err != nil || j < i {\n\t\t\t\t\treturn nil, errors.New(\"invalid range\")\n\t\t\t\t}\n\t\t\t\tr.start = i\n\t\t\t\tr.length = j - i + 1\n\t\t\t}\n\t\t}\n\t\tif r.start >= size {\n\t\t\tcontinue\n\t\t}\n\t\tif r.start+r.length > size {\n\t\t\tr.length = size - r.start\n\t\t}\n\t\tresult = append(result, r)\n\t}\n\treturn result, nil\n}\n" }, { "path": "components/execd/pkg/web/model/codeinterpreting.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage model\n\nimport (\n\t\"encoding/json\"\n\t\"errors\"\n\t\"fmt\"\n\t\"strings\"\n\n\t\"github.com/go-playground/validator/v10\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n)\n\n// RunCodeRequest represents a code execution request.\ntype RunCodeRequest struct {\n\tContext CodeContext `json:\"context,omitempty\"`\n\tCode string `json:\"code\" validate:\"required\"`\n}\n\nfunc (r *RunCodeRequest) Validate() error {\n\tvalidate := validator.New()\n\treturn validate.Struct(r)\n}\n\n// CodeContext tracks session metadata.\ntype CodeContext struct {\n\tID string `json:\"id,omitempty\"`\n\tCodeContextRequest `json:\",inline\"`\n}\n\ntype CodeContextRequest struct {\n\tLanguage string `json:\"language,omitempty\"`\n\tCwd string `json:\"cwd,omitempty\"`\n}\n\n// RunCommandRequest represents a shell command execution request.\ntype RunCommandRequest struct {\n\tCommand string `json:\"command\" validate:\"required\"`\n\tCwd string `json:\"cwd,omitempty\"`\n\tBackground bool `json:\"background,omitempty\"`\n\t// TimeoutMs caps execution duration; 0 uses server default.\n\tTimeoutMs int64 `json:\"timeout,omitempty\" validate:\"omitempty,gte=1\"`\n\n\tUid *uint32 `json:\"uid,omitempty\"`\n\tGid *uint32 `json:\"gid,omitempty\"`\n\tEnvs map[string]string `json:\"envs,omitempty\"`\n}\n\nfunc (r *RunCommandRequest) Validate() error {\n\tvalidate := validator.New()\n\tif err := validate.Struct(r); err != nil {\n\t\treturn err\n\t}\n\tif r.Gid != nil && r.Uid == nil {\n\t\treturn errors.New(\"uid is required when gid is provided\")\n\t}\n\treturn nil\n}\n\ntype ServerStreamEventType string\n\nconst (\n\tStreamEventTypeInit ServerStreamEventType = \"init\"\n\tStreamEventTypeStatus ServerStreamEventType = \"status\"\n\tStreamEventTypeError ServerStreamEventType = \"error\"\n\tStreamEventTypeStdout ServerStreamEventType = \"stdout\"\n\tStreamEventTypeStderr ServerStreamEventType = \"stderr\"\n\tStreamEventTypeResult ServerStreamEventType = \"result\"\n\tStreamEventTypeComplete ServerStreamEventType = \"execution_complete\"\n\tStreamEventTypeCount ServerStreamEventType = \"execution_count\"\n\tStreamEventTypePing ServerStreamEventType = \"ping\"\n)\n\n// ServerStreamEvent is emitted to clients over SSE.\ntype ServerStreamEvent struct {\n\tType ServerStreamEventType `json:\"type,omitempty\"`\n\tText string `json:\"text,omitempty\"`\n\tExecutionCount int `json:\"execution_count,omitempty\"`\n\tExecutionTime int64 `json:\"execution_time,omitempty\"`\n\tTimestamp int64 `json:\"timestamp,omitempty\"`\n\tResults map[string]any `json:\"results,omitempty\"`\n\tError *execute.ErrorOutput `json:\"error,omitempty\"`\n}\n\n// ToJSON serializes the event for streaming.\nfunc (s ServerStreamEvent) ToJSON() []byte {\n\tbytes, _ := json.Marshal(s)\n\treturn bytes\n}\n\n// Summary renders a lightweight, log-friendly string without JSON.\nfunc (s ServerStreamEvent) Summary() string {\n\tparts := []string{fmt.Sprintf(\"type=%s\", s.Type)}\n\tif s.Text != \"\" {\n\t\tparts = append(parts, fmt.Sprintf(\"text=%s\", truncateString(s.Text, 100)))\n\t}\n\tif s.ExecutionTime > 0 {\n\t\tparts = append(parts, fmt.Sprintf(\"elapsed_ms=%d\", s.ExecutionTime))\n\t}\n\tif len(s.Results) > 0 {\n\t\tparts = append(parts, fmt.Sprintf(\"results=%d\", len(s.Results)))\n\t}\n\tif s.Error != nil {\n\t\terrLabel := s.Error.EName\n\t\tif errLabel == \"\" {\n\t\t\terrLabel = \"error\"\n\t\t}\n\t\tparts = append(parts, fmt.Sprintf(\"error=%s: %s\", errLabel, truncateString(s.Error.EValue, 80)))\n\t}\n\treturn strings.Join(parts, \" \")\n}\n\nfunc truncateString(value string, maxCount int) string {\n\tif maxCount <= 0 || len(value) <= maxCount {\n\t\treturn value\n\t}\n\treturn value[:maxCount] + \"...\"\n}\n" }, { "path": "components/execd/pkg/web/model/codeinterpreting_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage model\n\nimport (\n\t\"encoding/json\"\n\t\"strings\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute\"\n\t\"github.com/stretchr/testify/require\"\n)\n\nfunc TestRunCodeRequestValidate(t *testing.T) {\n\treq := RunCodeRequest{\n\t\tCode: \"print('hi')\",\n\t}\n\trequire.NoError(t, req.Validate())\n\n\treq.Code = \"\"\n\trequire.Error(t, req.Validate(), \"expected validation error when code is empty\")\n}\n\nfunc TestRunCommandRequestValidate(t *testing.T) {\n\treq := RunCommandRequest{Command: \"ls\"}\n\trequire.NoError(t, req.Validate(), \"expected command validation success\")\n\n\treq.TimeoutMs = -100\n\trequire.Error(t, req.Validate(), \"expected validation error when timeout is negative\")\n\n\treq.TimeoutMs = 0\n\treq.Command = \"ls\"\n\trequire.NoError(t, req.Validate(), \"expected success when timeout is omitted/zero\")\n\n\treq.TimeoutMs = 10\n\treq.Command = \"\"\n\trequire.Error(t, req.Validate(), \"expected validation error when command is empty\")\n}\n\nfunc ptr32(v uint32) *uint32 { return &v }\n\nfunc TestRunCommandRequestValidateUidGid(t *testing.T) {\n\t// uid-only: valid\n\treq := RunCommandRequest{Command: \"id\", Uid: ptr32(1000)}\n\trequire.NoError(t, req.Validate(), \"expected success with uid only\")\n\n\t// uid + gid: valid\n\treq = RunCommandRequest{Command: \"id\", Uid: ptr32(1000), Gid: ptr32(1000)}\n\trequire.NoError(t, req.Validate(), \"expected success with uid and gid\")\n\n\t// gid-only: must be rejected\n\treq = RunCommandRequest{Command: \"id\", Gid: ptr32(1000)}\n\trequire.Error(t, req.Validate(), \"expected validation error when gid is set without uid\")\n}\n\nfunc TestServerStreamEventToJSON(t *testing.T) {\n\tevent := ServerStreamEvent{\n\t\tType: StreamEventTypeStdout,\n\t\tText: \"hello\",\n\t\tExecutionCount: 3,\n\t}\n\n\tdata := event.ToJSON()\n\tvar decoded ServerStreamEvent\n\trequire.NoError(t, json.Unmarshal(data, &decoded))\n\trequire.Equal(t, event.Type, decoded.Type)\n\trequire.Equal(t, event.Text, decoded.Text)\n\trequire.Equal(t, event.ExecutionCount, decoded.ExecutionCount)\n}\n\nfunc TestServerStreamEventSummary(t *testing.T) {\n\tlongText := strings.Repeat(\"a\", 120)\n\ttests := []struct {\n\t\tname string\n\t\tevent ServerStreamEvent\n\t\tcontains []string\n\t}{\n\t\t{\n\t\t\tname: \"basic stdout\",\n\t\t\tevent: ServerStreamEvent{\n\t\t\t\tType: StreamEventTypeStdout,\n\t\t\t\tText: \"hello\",\n\t\t\t\tExecutionCount: 2,\n\t\t\t},\n\t\t\tcontains: []string{\"type=stdout\", \"text=hello\"},\n\t\t},\n\t\t{\n\t\t\tname: \"truncated text and error\",\n\t\t\tevent: ServerStreamEvent{\n\t\t\t\tType: StreamEventTypeError,\n\t\t\t\tText: longText,\n\t\t\t\tError: &execute.ErrorOutput{EName: \"ValueError\", EValue: \"boom\"},\n\t\t\t},\n\t\t\tcontains: []string{\n\t\t\t\t\"type=error\",\n\t\t\t\t\"text=\" + strings.Repeat(\"a\", 100) + \"...\",\n\t\t\t\t\"error=ValueError: boom\",\n\t\t\t},\n\t\t},\n\t}\n\n\tfor _, tt := range tests {\n\t\tt.Run(tt.name, func(t *testing.T) {\n\t\t\tsummary := tt.event.Summary()\n\t\t\tfor _, want := range tt.contains {\n\t\t\t\trequire.Containsf(t, summary, want, \"summary missing %q\", want)\n\t\t\t}\n\t\t})\n\t}\n}\n" }, { "path": "components/execd/pkg/web/model/command.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage model\n\nimport \"time\"\n\n// CommandStatusResponse represents command status for REST APIs.\ntype CommandStatusResponse struct {\n\tID string `json:\"id\"`\n\tContent string `json:\"content,omitempty\"`\n\tRunning bool `json:\"running\"`\n\tExitCode *int `json:\"exit_code,omitempty\"`\n\tError string `json:\"error,omitempty\"`\n\tStartedAt time.Time `json:\"started_at,omitempty\"`\n\tFinishedAt *time.Time `json:\"finished_at,omitempty\"`\n}\n" }, { "path": "components/execd/pkg/web/model/error.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage model\n\ntype ErrorCode string\n\nconst (\n\tErrorCodeInvalidRequest ErrorCode = \"INVALID_REQUEST_BODY\"\n\tErrorCodeMissingQuery ErrorCode = \"MISSING_QUERY\"\n\tErrorCodeRuntimeError ErrorCode = \"RUNTIME_ERROR\"\n\tErrorCodeInvalidFile ErrorCode = \"INVALID_FILE\"\n\tErrorCodeInvalidFileContent ErrorCode = \"INVALID_FILE_CONTENT\"\n\tErrorCodeInvalidFileMetadata ErrorCode = \"INVALID_FILE_METADATA\"\n\tErrorCodeFileNotFound ErrorCode = \"FILE_NOT_FOUND\"\n\tErrorCodeUnknown ErrorCode = \"UNKNOWN\"\n\tErrorCodeContextNotFound ErrorCode = \"CONTEXT_NOT_FOUND\"\n)\n\ntype ErrorResponse struct {\n\tCode ErrorCode `json:\"code,omitempty\"`\n\tMessage string `json:\"message,omitempty\"`\n}\n" }, { "path": "components/execd/pkg/web/model/filesystem.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage model\n\nimport \"time\"\n\n// FileInfo represents file metadata including path and permissions\ntype FileInfo struct {\n\tPath string `json:\"path,omitempty\"`\n\tSize int64 `json:\"size\"`\n\tModifiedAt time.Time `json:\"modified_at,omitempty\"`\n\tCreatedAt time.Time `json:\"created_at,omitempty\"`\n\tPermission `json:\",inline\"`\n}\n\ntype FileMetadata struct {\n\tPath string `json:\"path,omitempty\"`\n\tPermission `json:\",inline\"`\n}\n\n// Permission represents file ownership and mode\ntype Permission struct {\n\tOwner string `json:\"owner\"`\n\tGroup string `json:\"group\"`\n\tMode int `json:\"mode\"`\n}\n\n// RenameFileItem represents a file rename operation\ntype RenameFileItem struct {\n\tSrc string `json:\"src,omitempty\"`\n\tDest string `json:\"dest,omitempty\"`\n}\n\n// ReplaceFileContentItem represents a content replacement operation\ntype ReplaceFileContentItem struct {\n\tOld string `json:\"old,omitempty\"`\n\tNew string `json:\"new,omitempty\"`\n}\n" }, { "path": "components/execd/pkg/web/model/header.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage model\n\nconst (\n\t// ApiAccessTokenHeader carries the auth token.\n\tApiAccessTokenHeader = \"X-EXECD-ACCESS-TOKEN\"\n)\n" }, { "path": "components/execd/pkg/web/model/metric.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage model\n\nimport \"time\"\n\n// Metrics represents system resource usage metrics\ntype Metrics struct {\n\tCpuCount float64 `json:\"cpu_count\"`\n\tCpuUsedPct float64 `json:\"cpu_used_pct\"`\n\tMemTotalMiB float64 `json:\"mem_total_mib\"`\n\tMemUsedMiB float64 `json:\"mem_used_mib\"`\n\tTimestamp int64 `json:\"timestamp\"`\n}\n\nfunc NewMetrics() *Metrics {\n\treturn &Metrics{\n\t\tCpuCount: 0,\n\t\tCpuUsedPct: 0,\n\t\tMemTotalMiB: 0,\n\t\tMemUsedMiB: 0,\n\t\tTimestamp: time.Now().UnixMilli(),\n\t}\n}\n" }, { "path": "components/execd/pkg/web/model/session.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage model\n\nimport (\n\t\"github.com/go-playground/validator/v10\"\n)\n\n// CreateSessionRequest is the request body for creating a bash session.\ntype CreateSessionRequest struct {\n\tCwd string `json:\"cwd,omitempty\"`\n}\n\n// CreateSessionResponse is the response for create_session.\ntype CreateSessionResponse struct {\n\tSessionID string `json:\"session_id\"`\n}\n\n// RunInSessionRequest is the request body for running code in an existing session.\ntype RunInSessionRequest struct {\n\tCode string `json:\"code\" validate:\"required\"`\n\tCwd string `json:\"cwd,omitempty\"`\n\tTimeoutMs int64 `json:\"timeout_ms,omitempty\" validate:\"omitempty,gte=0\"`\n}\n\n// Validate validates RunInSessionRequest.\nfunc (r *RunInSessionRequest) Validate() error {\n\tvalidate := validator.New()\n\treturn validate.Struct(r)\n}\n" }, { "path": "components/execd/pkg/web/proxy.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage web\n\nimport (\n\t\"net\"\n\t\"net/http\"\n\t\"net/http/httputil\"\n\t\"net/url\"\n\t\"strings\"\n\t\"time\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n)\n\nfunc ProxyMiddleware() gin.HandlerFunc {\n\treturn func(c *gin.Context) {\n\t\tif !strings.HasPrefix(c.Request.URL.Path, \"/proxy/\") {\n\t\t\tc.Next()\n\t\t\treturn\n\t\t}\n\n\t\tr := c.Request\n\t\tw := c.Writer\n\n\t\trest := strings.TrimPrefix(r.URL.Path, \"/proxy/\")\n\t\tparts := strings.SplitN(rest, \"/\", 2)\n\t\tif len(parts) == 0 || parts[0] == \"\" {\n\t\t\thttp.Error(w, \"port is required\", http.StatusBadRequest)\n\t\t\tc.Abort()\n\t\t\treturn\n\t\t}\n\n\t\tport := parts[0]\n\t\tpath := \"/\"\n\t\tif len(parts) == 2 && parts[1] != \"\" {\n\t\t\tpath += parts[1]\n\t\t}\n\n\t\ttarget := &url.URL{\n\t\t\tScheme: \"http\",\n\t\t\tHost: \"127.0.0.1:\" + port,\n\t\t\tPath: path,\n\t\t}\n\n\t\tisWebSocket := strings.ToLower(r.Header.Get(\"Upgrade\")) == \"websocket\"\n\n\t\tproxy := httputil.NewSingleHostReverseProxy(target)\n\t\t// Flush SSE chunks promptly; a small interval avoids buffering breaks chunked streams.\n\t\tproxy.FlushInterval = 200 * time.Millisecond\n\n\t\tproxy.Director = func(req *http.Request) {\n\t\t\treq.URL.Scheme = \"http\"\n\t\t\treq.URL.Host = \"127.0.0.1:\" + port\n\t\t\treq.URL.Path = path\n\t\t\treq.URL.RawQuery = r.URL.RawQuery\n\t\t\treq.URL.RawPath = \"\"\n\t\t\treq.RequestURI = \"\"\n\n\t\t\treq.Header.Set(\"X-Forwarded-For\", getClientIP(r))\n\t\t\treq.Header.Set(\"X-Forwarded-Proto\", \"http\")\n\t\t\treq.Header.Del(\"X-Forwarded-Host\")\n\n\t\t\tif isWebSocket {\n\t\t\t\treq.Header.Set(\"Connection\", \"Upgrade\")\n\t\t\t\treq.Header.Set(\"Upgrade\", \"websocket\")\n\t\t\t\treq.Header.Set(\"Sec-WebSocket-Version\", \"13\")\n\t\t\t\tif key := r.Header.Get(\"Sec-WebSocket-Key\"); key != \"\" {\n\t\t\t\t\treq.Header.Set(\"Sec-WebSocket-Key\", key)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tproxy.Transport = &http.Transport{\n\t\t\tDialContext: (&net.Dialer{\n\t\t\t\tTimeout: 600 * time.Second,\n\t\t\t\tKeepAlive: 30 * time.Second,\n\t\t\t}).DialContext,\n\t\t\tMaxIdleConns: 100,\n\t\t\tMaxIdleConnsPerHost: 100,\n\t\t\tIdleConnTimeout: 600 * time.Second,\n\t\t}\n\n\t\tproxy.ErrorHandler = func(rw http.ResponseWriter, req *http.Request, err error) {\n\t\t\tlog.Error(\"Proxy error: %v, request: %s %s\", err, req.Method, req.RequestURI)\n\t\t\thttp.Error(rw, \"Bad Gateway\", http.StatusBadGateway)\n\t\t}\n\n\t\tlog.Info(\"Proxy: %s %s -> %s (WebSocket: %v)\", r.Method, r.RequestURI, target.Host, isWebSocket)\n\n\t\tproxy.ServeHTTP(w, r)\n\t\tc.Abort()\n\t}\n}\n\nfunc getClientIP(r *http.Request) string {\n\tif ip := r.Header.Get(\"X-Forwarded-For\"); ip != \"\" {\n\t\treturn strings.Split(ip, \",\")[0]\n\t}\n\tif ip := r.Header.Get(\"X-Real-IP\"); ip != \"\" {\n\t\treturn ip\n\t}\n\treturn r.RemoteAddr\n}\n" }, { "path": "components/execd/pkg/web/router.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage web\n\nimport (\n\t\"net/http\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\t\"github.com/alibaba/opensandbox/execd/pkg/log\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/controller\"\n\t\"github.com/alibaba/opensandbox/execd/pkg/web/model\"\n)\n\n// NewRouter builds a Gin engine with all execd routes.\nfunc NewRouter(accessToken string) *gin.Engine {\n\tgin.SetMode(gin.ReleaseMode)\n\tr := gin.New()\n\tr.Use(gin.Recovery())\n\tr.Use(logMiddleware(), accessTokenMiddleware(accessToken), ProxyMiddleware())\n\n\tr.GET(\"/ping\", controller.PingHandler)\n\n\tfiles := r.Group(\"/files\")\n\t{\n\t\tfiles.DELETE(\"\", withFilesystem(func(c *controller.FilesystemController) { c.RemoveFiles() }))\n\t\tfiles.GET(\"/info\", withFilesystem(func(c *controller.FilesystemController) { c.GetFilesInfo() }))\n\t\tfiles.POST(\"/mv\", withFilesystem(func(c *controller.FilesystemController) { c.RenameFiles() }))\n\t\tfiles.POST(\"/permissions\", withFilesystem(func(c *controller.FilesystemController) { c.ChmodFiles() }))\n\t\tfiles.GET(\"/search\", withFilesystem(func(c *controller.FilesystemController) { c.SearchFiles() }))\n\t\tfiles.POST(\"/replace\", withFilesystem(func(c *controller.FilesystemController) { c.ReplaceContent() }))\n\t\tfiles.POST(\"/upload\", withFilesystem(func(c *controller.FilesystemController) { c.UploadFile() }))\n\t\tfiles.GET(\"/download\", withFilesystem(func(c *controller.FilesystemController) { c.DownloadFile() }))\n\t}\n\n\tdirectories := r.Group(\"/directories\")\n\t{\n\t\tdirectories.POST(\"\", withFilesystem(func(c *controller.FilesystemController) { c.MakeDirs() }))\n\t\tdirectories.DELETE(\"\", withFilesystem(func(c *controller.FilesystemController) { c.RemoveDirs() }))\n\t}\n\n\tcode := r.Group(\"/code\")\n\t{\n\t\tcode.POST(\"\", withCode(func(c *controller.CodeInterpretingController) { c.RunCode() }))\n\t\tcode.DELETE(\"\", withCode(func(c *controller.CodeInterpretingController) { c.InterruptCode() }))\n\t\tcode.POST(\"/context\", withCode(func(c *controller.CodeInterpretingController) { c.CreateContext() }))\n\t\tcode.GET(\"/contexts\", withCode(func(c *controller.CodeInterpretingController) { c.ListContexts() }))\n\t\tcode.DELETE(\"/contexts\", withCode(func(c *controller.CodeInterpretingController) { c.DeleteContextsByLanguage() }))\n\t\tcode.DELETE(\"/contexts/:contextId\", withCode(func(c *controller.CodeInterpretingController) { c.DeleteContext() }))\n\t\tcode.GET(\"/contexts/:contextId\", withCode(func(c *controller.CodeInterpretingController) { c.GetContext() }))\n\t}\n\n\tsession := r.Group(\"/session\")\n\t{\n\t\tsession.POST(\"\", withCode(func(c *controller.CodeInterpretingController) { c.CreateSession() }))\n\t\tsession.POST(\"/:sessionId/run\", withCode(func(c *controller.CodeInterpretingController) { c.RunInSession() }))\n\t\tsession.DELETE(\"/:sessionId\", withCode(func(c *controller.CodeInterpretingController) { c.DeleteSession() }))\n\t}\n\n\tcommand := r.Group(\"/command\")\n\t{\n\t\tcommand.POST(\"\", withCode(func(c *controller.CodeInterpretingController) { c.RunCommand() }))\n\t\tcommand.DELETE(\"\", withCode(func(c *controller.CodeInterpretingController) { c.InterruptCommand() }))\n\t\tcommand.GET(\"/status/:id\", withCode(func(c *controller.CodeInterpretingController) { c.GetCommandStatus() }))\n\t\tcommand.GET(\"/:id/logs\", withCode(func(c *controller.CodeInterpretingController) { c.GetBackgroundCommandOutput() }))\n\t}\n\n\tmetric := r.Group(\"/metrics\")\n\t{\n\t\tmetric.GET(\"\", withMetric(func(c *controller.MetricController) { c.GetMetrics() }))\n\t\tmetric.GET(\"/watch\", withMetric(func(c *controller.MetricController) { c.WatchMetrics() }))\n\t}\n\n\treturn r\n}\n\nfunc withFilesystem(fn func(*controller.FilesystemController)) gin.HandlerFunc {\n\treturn func(ctx *gin.Context) {\n\t\tfn(controller.NewFilesystemController(ctx))\n\t}\n}\n\nfunc withCode(fn func(*controller.CodeInterpretingController)) gin.HandlerFunc {\n\treturn func(ctx *gin.Context) {\n\t\tfn(controller.NewCodeInterpretingController(ctx))\n\t}\n}\n\nfunc withMetric(fn func(*controller.MetricController)) gin.HandlerFunc {\n\treturn func(ctx *gin.Context) {\n\t\tfn(controller.NewMetricController(ctx))\n\t}\n}\n\nfunc accessTokenMiddleware(token string) gin.HandlerFunc {\n\treturn func(ctx *gin.Context) {\n\t\tif token == \"\" {\n\t\t\tctx.Next()\n\t\t\treturn\n\t\t}\n\n\t\trequestedToken := ctx.GetHeader(model.ApiAccessTokenHeader)\n\t\tif requestedToken == \"\" || requestedToken != token {\n\t\t\tctx.AbortWithStatusJSON(http.StatusUnauthorized, map[string]any{\n\t\t\t\t\"error\": \"Unauthorized: invalid or missing header \" + model.ApiAccessTokenHeader,\n\t\t\t})\n\t\t\treturn\n\t\t}\n\n\t\tctx.Next()\n\t}\n}\n\nfunc logMiddleware() gin.HandlerFunc {\n\treturn func(ctx *gin.Context) {\n\t\tlog.Info(\"Requested: %v - %v\", ctx.Request.Method, ctx.Request.URL.String())\n\t\tctx.Next()\n\t}\n}\n" }, { "path": "components/execd/tests/jupyter.sh", "content": "#!/bin/bash\n# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\nexport JUPYTER_PORT=54321\nexport JUPYTER_TOKEN=opensandboxexecdintegrationtest\n\ninstall_jupyter() {\n\t# install jupyter notebook for integration testing\n\tpython --version\n\tpip install ipykernel jupyter\n\n\techo \"Starting jupyter notebook ...\"\n\tjupyter notebook --ip=0.0.0.0 --port=$JUPYTER_PORT --allow-root --no-browser --NotebookApp.token=$JUPYTER_TOKEN >/tmp/jupyter.log 2>&1 &\n\n\tsleep 3\n}\n" }, { "path": "components/execd/tests/smoke.sh", "content": "#!/bin/bash\n# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\nset -euxo pipefail\n\nsource tests/jupyter.sh\ninstall_jupyter\n\nexport EXECD_API_GRACE_SHUTDOWN=500ms\nexport EXECD_LOG_FILE=execd.log\n./bin/execd -jupyter-host=http://127.0.0.1:${JUPYTER_PORT} --jupyter-token=${JUPYTER_TOKEN} --log-level=7 >startup.log 2>&1 &\n" }, { "path": "components/execd/tests/smoke_api.py", "content": "#!/usr/bin/env python3\n\n# Copyright 2025 Alibaba Group Holding Ltd.\n# \n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n# \n# http://www.apache.org/licenses/LICENSE-2.0\n# \n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"\nSimple smoke tests for execd APIs.\n\nPrerequisites:\n- execd server running locally (default http://localhost:44772)\n- Optional: set env BASE_URL to override\n- Optional: set env API_TOKEN if server expects X-EXECD-ACCESS-TOKEN\n\"\"\"\n\nimport json\nimport os\nimport sys\nimport time\nimport uuid\nimport tempfile\nimport pathlib\n\nimport requests\n\nBASE_URL = os.environ.get(\"BASE_URL\", \"http://localhost:44772\").rstrip(\"/\")\nAPI_TOKEN = os.environ.get(\"API_TOKEN\")\n\nHEADERS = {}\nif API_TOKEN:\n HEADERS[\"X-EXECD-ACCESS-TOKEN\"] = API_TOKEN\n\nsession = requests.Session()\nsession.headers.update(HEADERS)\n\n\ndef expect(cond: bool, msg: str):\n if not cond:\n raise SystemExit(msg)\n\n\ndef sse_get_command_id() -> str:\n url = f\"{BASE_URL}/command\"\n payload = {\"command\": \"echo smoke-command && sleep 1\", \"background\": True}\n with session.post(url, json=payload, stream=True, timeout=15) as resp:\n expect(resp.status_code == 200, f\"SSE start failed: {resp.status_code} {resp.text}\")\n for line in resp.iter_lines():\n if not line or not line.startswith(b\"data:\"):\n # controller emits raw JSON lines without SSE 'data:' prefix\n try:\n data = json.loads(line.decode())\n except Exception:\n continue\n else:\n data = json.loads(line[len(b\"data:\") :].decode())\n if data.get(\"type\") == \"init\":\n cmd_id = data.get(\"text\")\n expect(cmd_id, \"missing command id in init event\")\n return cmd_id\n raise SystemExit(\"Failed to obtain command id from SSE\")\n\n\ndef wait_status(cmd_id: str, timeout: float = 15.0) -> dict:\n url = f\"{BASE_URL}/command/status/{cmd_id}\"\n deadline = time.time() + timeout\n last = None\n while time.time() < deadline:\n r = session.get(url, timeout=5)\n expect(r.status_code == 200, f\"status failed: {r.status_code} {r.text}\")\n last = r.json()\n if not last.get(\"running\", True):\n return last\n time.sleep(0.3)\n return last\n\n\ndef fetch_logs(cmd_id: str, cursor: int = 0):\n url = f\"{BASE_URL}/command/{cmd_id}/logs\"\n r = session.get(url, params={\"cursor\": cursor}, timeout=10)\n expect(r.status_code == 200, f\"logs failed: {r.status_code} {r.text}\")\n return r.text, r.headers.get(\"EXECD-COMMANDS-TAIL-CURSOR\")\n\n\ndef sse_disconnect_should_stop_ping():\n \"\"\"\n Open an SSE stream for a long-running command, receive init, then close the\n client side early to ensure the server handles disconnects (ping loop should\n stop). We verify the server is still responsive afterwards.\n \"\"\"\n url = f\"{BASE_URL}/command\"\n payload = {\n # long command so the server would keep pinging if not cancelled\n \"command\": \"sh -c 'echo long-run-start && sleep 20 && echo long-run-end'\",\n \"background\": False,\n }\n\n with session.post(url, json=payload, stream=True, timeout=10) as resp:\n expect(resp.status_code == 200, f\"SSE start failed: {resp.status_code} {resp.text}\")\n for line in resp.iter_lines():\n if not line:\n continue\n try:\n if line.startswith(b\"data:\"):\n data = json.loads(line[len(b\"data:\") :].decode())\n else:\n data = json.loads(line.decode())\n except Exception:\n continue\n if data.get(\"type\") == \"init\":\n break\n # explicitly close to simulate client drop\n resp.close()\n\n # Give server a moment to observe disconnect and ensure API remains healthy\n time.sleep(1)\n pong = session.get(f\"{BASE_URL}/ping\", timeout=5)\n expect(pong.status_code == 200, \"ping failed after SSE disconnect\")\n\n\ndef upload_and_download():\n tmp_dir = f\"/tmp/execd-smoke-{uuid.uuid4().hex}\"\n path = f\"{tmp_dir}/hello.txt\"\n metadata = json.dumps({\"path\": path})\n files = {\n \"metadata\": (\"metadata\", metadata, \"application/json\"),\n \"file\": (\"file\", b\"hello execd\\n\", \"application/octet-stream\"),\n }\n up = session.post(f\"{BASE_URL}/files/upload\", files=files, timeout=10)\n expect(up.status_code == 200, f\"upload failed: {up.status_code} {up.text}\")\n\n down = session.get(f\"{BASE_URL}/files/download\", params={\"path\": path}, timeout=10)\n expect(down.status_code == 200, f\"download failed: {down.status_code} {down.text}\")\n expect(down.content == b\"hello execd\\n\", \"downloaded content mismatch\")\n\n\ndef filesystem_smoke():\n base_dir = os.path.join(tempfile.gettempdir(), f\"execd-smoke-{uuid.uuid4().hex}\")\n sub_dir = os.path.join(base_dir, \"sub\")\n file_path = os.path.join(sub_dir, \"hello.txt\")\n renamed_path = os.path.join(sub_dir, \"hello_renamed.txt\")\n\n # create dirs\n mk = session.post(f\"{BASE_URL}/directories\", json={sub_dir: {\"mode\": 0}}, timeout=10)\n expect(mk.status_code == 200, f\"mkdir failed: {mk.status_code} {mk.text}\")\n\n # upload a file\n metadata = json.dumps({\"path\": file_path})\n files = {\n \"metadata\": (\"metadata\", metadata, \"application/json\"),\n \"file\": (\"file\", b\"hello execd\\n\", \"application/octet-stream\"),\n }\n up = session.post(f\"{BASE_URL}/files/upload\", files=files, timeout=10)\n expect(up.status_code == 200, f\"upload failed: {up.status_code} {up.text}\")\n\n # get info\n info = session.get(f\"{BASE_URL}/files/info\", params={\"path\": [file_path]}, timeout=10)\n expect(info.status_code == 200, f\"info failed: {info.status_code} {info.text}\")\n\n # search\n search = session.get(f\"{BASE_URL}/files/search\", params={\"path\": base_dir, \"pattern\": \"*.txt\"}, timeout=10)\n expect(search.status_code == 200, f\"search failed: {search.status_code} {search.text}\")\n found = False\n for f in search.json():\n p = f.get(\"path\")\n if not p:\n continue\n if pathlib.Path(p).resolve() == pathlib.Path(file_path).resolve():\n found = True\n break\n expect(found, \"search did not find file\")\n\n # replace content\n rep = session.post(\n f\"{BASE_URL}/files/replace\",\n json={file_path: {\"old\": \"hello\", \"new\": \"hi\"}},\n timeout=10,\n )\n expect(rep.status_code == 200, f\"replace failed: {rep.status_code} {rep.text}\")\n\n # download to verify replace\n down = session.get(f\"{BASE_URL}/files/download\", params={\"path\": file_path}, timeout=10)\n expect(down.status_code == 200, f\"download failed: {down.status_code} {down.text}\")\n expect(down.content == b\"hi execd\\n\", \"replace content mismatch\")\n\n # chmod (mode only)\n chmod = session.post(f\"{BASE_URL}/files/permissions\", json={file_path: {\"mode\": 644}}, timeout=10)\n expect(chmod.status_code == 200, f\"chmod failed: {chmod.status_code} {chmod.text}\")\n\n # rename\n mv = session.post(\n f\"{BASE_URL}/files/mv\",\n json=[{\"src\": file_path, \"dest\": renamed_path}],\n timeout=10,\n )\n expect(mv.status_code == 200, f\"rename failed: {mv.status_code} {mv.text}\")\n\n # remove file\n rm_file = session.delete(f\"{BASE_URL}/files\", params={\"path\": [renamed_path]}, timeout=10)\n expect(rm_file.status_code == 200, f\"remove file failed: {rm_file.status_code} {rm_file.text}\")\n\n # remove dir\n rm_dir = session.delete(f\"{BASE_URL}/directories\", params={\"path\": [base_dir]}, timeout=10)\n expect(rm_dir.status_code == 200, f\"remove dir failed: {rm_dir.status_code} {rm_dir.text}\")\n\n\ndef main():\n print(f\"[+] base: {BASE_URL}\")\n r = session.get(f\"{BASE_URL}/ping\", timeout=5)\n expect(r.status_code == 200, \"ping failed\")\n print(\"[+] ping ok\")\n\n sse_disconnect_should_stop_ping()\n print(\"[+] SSE disconnect handled\")\n\n cmd_id = sse_get_command_id()\n print(f\"[+] command id: {cmd_id}\")\n\n status = wait_status(cmd_id)\n print(f\"[+] status: {status}\")\n\n logs, cursor = fetch_logs(cmd_id, cursor=0)\n print(f\"[+] logs (cursor={cursor}):\\n{logs}\")\n\n filesystem_smoke()\n print(\"[+] filesystem APIs ok\")\n\n print(\"[+] smoke tests PASS\")\n\n\nif __name__ == \"__main__\":\n try:\n main()\n except SystemExit as exc:\n print(f\"[!] smoke tests FAIL: {exc}\", file=sys.stderr)\n sys.exit(1)" }, { "path": "components/ingress/.golangci.yml", "content": "run:\n skip-dirs:\n - vendor\n - tests\n - scripts\n skip-files:\n - .*/zz_generated.deepcopy.go\n - .*/mock/*.go\n tests: false\n timeout: 10m\nlinters-settings:\n funlen:\n lines: 500\n statements: 200\n gocyclo:\n min-complexity: 40\n gosimple:\n checks: [\"S1019\", \"S1002\"]\n staticcheck:\n checks: [\"SA4006\"]\n govet:\n enable:\n - asmdecl\n - assign\n - atomic\n - atomicalign\n - bools\n - buildtag\n - cgocall\n - copylocks\n - deepequalerrors\n - errorsas\n - findcall\n - framepointer\n - httpresponse\n - ifaceassert\n - lostcancel\n - nilfunc\n - nilness\n - reflectvaluecompare\n - shift\n - sigchanyzer\n - sortslice\n - stdmethods\n - stringintconv\n - testinggoroutine\n - tests\n - unmarshal\n - unreachable\n - unsafeptr\n - unusedresult\n - printf\n disable:\n - composites\n - loopclosure\n - fieldalignment\n - shadow\n - structtag\n - unusedwrite\n errcheck:\n exclude-functions:\n - flag.Set\n - os.Setenv\n - os.Unsetenv\n - logger.Sync\n - fmt.Fprintf\n - fmt.Fprintln\n - (io.Closer).Close\n - (io.ReadCloser).Close\n - (k8s.io/client-go/tools/cache.SharedInformer).AddEventHandler\n nestif:\n # ๅคๆ‚ๅบฆๅคงไบŽ32็š„่ฎคไธบ้˜ปๅกž\n min-complexity: 32\n goconst:\n # Minimal length of string constant.\n # Default: 3\n min-len: 3\n # Minimum occurrences of constant string count to trigger issue.\n # Default: 3\n min-occurrences: 3\n # Ignore test files.\n # Default: false\n ignore-tests: true\n match-constant: false\n numbers: true\n min: 2\n max: 10\n ignore-calls: true\n gosec:\n includes:\n - G101 # Look for hard coded credentials\n - G102 # Bind to all interfaces\n - G103 # Audit the use of unsafe block\n - G104 # Audit errors not checked\n - G106 # Audit the use of ssh.InsecureIgnoreHostKey\n - G107 # Url provided to HTTP request as taint input\n - G108 # Profiling endpoint automatically exposed on /debug/pprof\n - G109 # Potential Integer overflow made by strconv.Atoi result conversion to int16/32\n - G110 # Potential DoS vulnerability via decompression bomb\n - G111 # Potential directory traversal\n - G112 # Potential slowloris attack\n - G113 # Usage of Rat.SetString in math/big with an overflow (CVE-2022-23772)\n # - G114 # Use of net/http serve function that has no support for setting timeouts\n - G201 # SQL query construction using format string\n - G202 # SQL query construction using string concatenation\n - G203 # Use of unescaped data in HTML templates\n #- G204 # Audit use of command execution\n - G301 # Poor file permissions used when creating a directory\n - G302 # Poor file permissions used with chmod\n - G303 # Creating tempfile using a predictable path\n - G304 # File path provided as taint input\n - G305 # File traversal when extracting zip/tar archive\n - G306 # Poor file permissions used when writing to a new file\n - G307 # Deferring a method which returns an error\n #- G401 # Detect the usage of DES, RC4, MD5 or SHA1\n - G402 # Look for bad TLS connection settings\n - G403 # Ensure minimum RSA key length of 2048 bits\n - G404 # Insecure random number source (rand)\n #- G501 # Import blocklist: crypto/md5\n - G502 # Import blocklist: crypto/des\n - G503 # Import blocklist: crypto/rc4\n - G504 # Import blocklist: net/http/cgi\n - G505 # Import blocklist: crypto/sha1\n - G601 # Implicit memory aliasing of items from a range statement\n # Exclude generated files\n # Default: false\n exclude-generated: true\n # Filter out the issues with a lower severity than the given value.\n # Valid options are: low, medium, high.\n # Default: low\n severity: medium\n # Filter out the issues with a lower confidence than the given value.\n # Valid options are: low, medium, high.\n # Default: low\n confidence: medium\n # Concurrency value.\n # Default: the number of logical CPUs usable by the current process.\n concurrency: 12\n # To specify the configuration of rules.\n config:\n # Globals are applicable to all rules.\n global:\n nosec: true\n show-ignored: true\n audit: true\n G101:\n # Regexp pattern for variables and constants to find.\n # Default: \"(?i)passwd|pass|password|pwd|secret|token|pw|apiKey|bearer|cred\"\n pattern: \"(?i)example\"\n # If true, complain about all cases (even with low entropy).\n # Default: false\n ignore_entropy: false\n # Maximum allowed entropy of the string.\n # Default: \"80.0\"\n entropy_threshold: \"80.0\"\n per_char_threshold: \"3.0\"\n truncate: \"32\"\n G104:\n fmt:\n - Fscanf\n G111:\n # Regexp pattern to find potential directory traversal.\n # Default: \"http\\\\.Dir\\\\(\\\"\\\\/\\\"\\\\)|http\\\\.Dir\\\\('\\\\/'\\\\)\"\n pattern: \"custom\\\\.Dir\\\\(\\\\)\"\n # Maximum allowed permissions mode for os.Mkdir and os.MkdirAll\n # Default: \"0750\"\n G301: \"0750\"\n # Maximum allowed permissions mode for os.OpenFile and os.Chmod\n # Default: \"0600\"\n G302: \"0600\"\n # Maximum allowed permissions mode for os.WriteFile and ioutil.WriteFile\n # Default: \"0600\"\n G306: \"0600\"\n nilnil:\n checked-types:\n - ptr\n - map\n - chan\n depguard:\n rules:\n prevent_unmaintained_packages:\n list-mode: lax # allow unless explicitely denied\n files:\n - $all\n - \"!$test\"\n allow:\n - $gostd\n - path/filepath\n deny:\n - pkg: io/ioutil\n desc: \"replaced by io and os packages since Go 1.16: https://tip.golang.org/doc/go1.16#ioutil\"\n - pkg: path\n desc: \"replaced by cross-platform package path/filepath\"\n gci:\n # Section configuration to compare against.\n # Section names are case-insensitive and may contain parameters in ().\n # The default order of sections is `standard > default > custom > blank > dot > alias > localmodule`,\n # If `custom-order` is `true`, it follows the order of `sections` option.\n # Default: [\"standard\", \"default\"]\n sections:\n - standard # Standard section: captures all standard packages.\n - default # Default section: contains all imports that could not be matched to another section type.:\n - prefix(github.com/org/project) # Custom section: groups all imports with the specified Prefix.\n - blank # Blank section: contains all blank imports. This section is not present unless explicitly enabled.\n - dot # Dot section: contains all dot imports. This section is not present unless explicitly enabled.\n - localmodule # Local module section: contains all local packages. This section is not present unless explicitly enabled.\n # Skip generated files.\n # Default: true\n skip-generated: true\n # Enable custom order of sections.\n # If `true`, make the section order the same as the order of `sections`.\n # Default: false\n custom-order: true\n # Drops lexical ordering for custom sections.\n # Default: false\n no-lex-order: true\n forbidigo:\n forbid:\n # Forbid spew Dump, whether it is called as function or method.\n # Depends on analyze-types below.\n - ^spew\\.(ConfigState\\.)?Dump$\n # The package name might be ambiguous.\n # The full import path can be used as additional criteria.\n # Depends on analyze-types below.\n - p: ^v1.Dump$\n pkg: ^example.com/pkg/api/v1$\n\nlinters:\n enable:\n - asasalint\n - asciicheck\n - bidichk\n - bodyclose\n # - cyclop\n - decorder\n - depguard\n - errcheck\n # - errchkjson\n - errorlint\n - forbidigo\n # - forcetypeassert\n - funlen\n - ineffassign\n - gocognit\n - gocyclo\n - goheader\n - gomodguard\n - goprintffuncname\n - gosimple\n - gosec\n - grouper\n - importas\n - maintidx\n - misspell\n - nakedret\n - nilerr\n - nilnil\n # - noctx\n - nosprintfhostport\n - paralleltest\n - predeclared\n # - promlinter\n - reassign\n - sqlclosecheck\n - staticcheck\n - tenv\n - testpackage\n - tparallel\n # del\n # - typecheck\n - usestdlibvars\n - nestif\n - unused\n - makezero\n - govet\n - goconst\n - gci\n # - rowserrcheck\n # 1.59 version no new lints\n # 1.58 version new lints\n # - fatcontext\n - canonicalheader\n # 1.57 version new lints\n - copyloopvar\n - intrange\n # 1.56 version new lints\n - spancheck\n # 1.55 version new lints\n - gochecksumtype\n - perfsprint\n - sloglint\n - testifylint\n - mirror\n - zerologlint\n # 1.51 version new lints\n - gocheckcompilerdirectives\n # 1.50 version new lints\n - testableexamples\n\nissues:\n # Note: path identifiers are regular expressions, hence the \\.go suffixes.\n exclude-rules:\n - path: main\\.go\n linters:\n - forbidigo\n - path: _test\\.go\n linters:\n - dogsled\n - errcheck\n - goconst\n - gosec\n - ineffassign\n - maintidx\n - typecheck\n - path: \\.go$\n text: \"should have a package comment\"\n - path: \\.go$\n text: 'exported (.+) should have comment( \\(or a comment on this block\\))? or be unexported'\n - path: \\.go$\n text: \"fmt.Sprintf can be replaced with string concatenation\"\n" }, { "path": "components/ingress/DEVELOPMENT.md", "content": "# Development Guide (Quick)\n\n## Prerequisites\n- Go 1.24+\n- Docker (optional, for image build)\n- Access to a Kubernetes cluster with BatchSandbox CRD installed.\n\n## Install deps\n```bash\ncd components/ingress\ngo mod tidy && go mod vendor\n```\n\n## Build & Run\n```bash\nmake build # binary at bin/ingress with ldflags version info\n./bin/ingress \\\n --namespace \\\n --port 28888 \\\n --log-level info\n```\n\n## Tests & Lint\n```bash\nmake test # go test ./...\ngo vet ./... # included in make build\n```\n\n## Docker (with build args)\n```bash\ndocker build \\\n --build-arg VERSION=$(git describe --tags --always --dirty) \\\n --build-arg GIT_COMMIT=$(git rev-parse HEAD) \\\n --build-arg BUILD_TIME=$(date -u +\"%Y-%m-%dT%H:%M:%SZ\") \\\n -t opensandbox/ingress:dev .\n```\n\n## Key Paths\n- `main.go` โ€” entrypoint, HTTP routes, provider initialization.\n- `pkg/proxy/` โ€” HTTP/WebSocket reverse proxy logic.\n- `pkg/sandbox/` โ€” Sandbox provider abstraction and BatchSandbox implementation.\n- `version/` โ€” build metadata (ldflags).\n\n## Tips\n- Health check: `/status.ok`\n- Proxy endpoint: `/` (routes based on `OpenSandbox-Ingress-To` header or Host)\n- Env overrides: `VERSION/GIT_COMMIT/BUILD_TIME` usable via Makefile and build.sh.\n- BatchSandbox must have `sandbox.opensandbox.io/endpoints` annotation with JSON array of IPs.\n\n" }, { "path": "components/ingress/Dockerfile", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nFROM golang:1.24.0 AS builder\n\nWORKDIR /build\n\nARG VERSION=dev\nARG GIT_COMMIT=unknown\nARG BUILD_TIME=unknown\n\nCOPY kubernetes ./kubernetes\n# Prepare local modules to satisfy replace directives.\nCOPY components/internal/go.mod components/internal/go.sum ./components/internal/\nCOPY components/ingress/go.mod components/ingress/go.sum ./components/ingress/\n\nWORKDIR /build\n\nRUN cd components/internal && go mod download\nRUN cd components/ingress && go mod download\n\n# Copy sources.\nCOPY components/internal ./components/internal\nCOPY components/ingress/. ./components/ingress\n\nWORKDIR /build/components/ingress\n\nRUN CGO_ENABLED=0 go build \\\n -ldflags \"-X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \\\n -X 'github.com/alibaba/opensandbox/internal/version.BuildTime=${BUILD_TIME}' \\\n -X 'github.com/alibaba/opensandbox/internal/version.GitCommit=${GIT_COMMIT}'\" \\\n -o /build/ingress ./main.go\n\nFROM alpine:latest\n\nCOPY --from=builder /build/ingress .\n\nENTRYPOINT [\"./ingress\"]\n" }, { "path": "components/ingress/Makefile", "content": ".PHONY: fmt\nfmt: ## Run go fmt against code.\n\tgo fmt ./...\n\n.PHONY: vet\nvet: ## Run go vet against code.\n\tgo mod tidy && go mod vendor\n\tgo vet ./...\n\n.PHONY: test\ntest: vet ## Run tests\n\tgo test -v -coverpkg=./... ./pkg/...\n\n##@ Linter\n\n.PHONY: install-golint\ninstall-golint:\n\t@if ! command -v golangci-lint &> /dev/null; then \\\n \t\techo \"installing golangci-lint...\"; \\\n \t\tgo install github.com/golangci/golangci-lint/cmd/golangci-lint@latest; \\\n \telse \\\n \t echo \"golangci-lint already installed\"; \\\n\tfi\n\n.PHONY: golint\ngolint: fmt install-golint\n\tgolangci-lint run -v --fix ./...\n\nVERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo \"dev\")\nGIT_COMMIT ?= $(shell git rev-parse HEAD 2>/dev/null || echo \"unknown\")\nBUILD_TIME ?= $(shell date -u +\"%Y-%m-%dT%H:%M:%SZ\")\nLDFLAGS := -X 'github.com/alibaba/opensandbox/internal/version.Version=$(VERSION)' \\\n\t-X 'github.com/alibaba/opensandbox/internal/version.BuildTime=$(BUILD_TIME)' \\\n\t-X 'github.com/alibaba/opensandbox/internal/version.GitCommit=$(GIT_COMMIT)'\n\n.PHONY: build\nbuild: vet ## Build the binary.\n\t@mkdir -p bin\n\tgo build -ldflags \"$(LDFLAGS)\" -o bin/router main.go\n\n.PHONY: clean\nclean: ## Clean build artifacts.\n\trm -rf bin/ vendor/\n" }, { "path": "components/ingress/README.md", "content": "# OpenSandbox Ingress\n\n## Overview\n- HTTP/WebSocket reverse proxy that routes to sandbox instances.\n- Watches sandbox CRs (BatchSandbox or AgentSandbox, chosen by `--provider-type`) in a target Namespace:\n - BatchSandbox: reads endpoints from `sandbox.opensandbox.io/endpoints` annotation.\n - AgentSandbox: reads `status.serviceFQDN`.\n- Exposes `/status.ok` health check; prints build metadata (version, commit, time, Go/platform) at startup.\n\n## Quick Start\n```bash\ngo run main.go \\\n --namespace \\\n --provider-type \\\n --mode \\\n --port 28888 \\\n --log-level info\n```\nEndpoints: `/` (proxy), `/status.ok` (health).\n\n## Routing Modes\n\nThe ingress supports two routing modes for discovering sandbox instances:\n\n### Header Mode (default: `--mode header`)\n\nRoutes requests based on the `OpenSandbox-Ingress-To` header or the `Host` header.\n\n**Format:**\n- Header: `OpenSandbox-Ingress-To: -`\n- Host: `-.`\n\n**Example:**\n```bash\n# Using OpenSandbox-Ingress-To header\ncurl -H \"OpenSandbox-Ingress-To: my-sandbox-8080\" https://ingress.opensandbox.io/api/users\n\n# Using Host header\ncurl -H \"Host: my-sandbox-8080.example.com\" https://ingress.opensandbox.io/api/users\n```\n\n**Parsing logic:**\n- Extracts sandbox ID and port from the format `-`\n- The last segment after the last `-` is treated as the port\n- Everything before the last `-` is treated as the sandbox ID\n\n### URI Mode (`--mode uri`)\n\nRoutes requests based on the URI path structure.\n\n**Format:**\n\n`///`\n\n**Example:**\n```bash\n# Request to sandbox \"my-sandbox\" on port 8080, forwarding to /api/users\ncurl https://ingress.opensandbox.io/my-sandbox/8080/api/users\n\n# WebSocket example\nwss://ingress.opensandbox.io/my-sandbox/8080/ws\n```\n\n**Parsing logic:**\n- First path segment: sandbox ID\n- Second path segment: sandbox port\n- Remaining path: forwarded to the target sandbox as the request URI\n- If no remaining path is provided, defaults to `/`\n\n**Use cases:**\n- When you cannot modify HTTP headers\n- When you need path-based routing\n- For simpler client configuration without custom headers\n\n## Auto-Renew on Ingress Access (OSEP-0009)\n\nWhen enabled, the ingress publishes **renew-intent** events to a Redis list on each proxied request (after resolving the sandbox). The OpenSandbox server consumes these events and may extend sandbox expiration for sandboxes that opted in at creation time. See [OSEP-0009](https://github.com/alibaba/opensandbox/blob/main/oseps/0009-auto-renew-sandbox-on-ingress-access.md) for the full design.\n\n**Requirements:** The server must have auto-renew and Redis consumer enabled; the sandbox must be created with `extensions[\"auto_renew_on_access\"]=\"true\"`. This feature is best-effort and disabled by default.\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--renew-intent-enabled` | `false` | Enable publishing renew-intent events to Redis |\n| `--renew-intent-redis-dsn` | `redis://127.0.0.1:6379/0` | Redis DSN (may include `user:password@`) |\n| `--renew-intent-queue-key` | `opensandbox:renew:intent` | Redis List key for intent payloads |\n| `--renew-intent-queue-max-len` | `0` | Max list length (0 = no cap); LTRIM applied when > 0 |\n| `--renew-intent-min-interval` | `60` | Min seconds between intents per sandbox (client-side throttle) |\n\n**Example (with Redis):**\n```bash\ngo run main.go \\\n --namespace opensandbox \\\n --renew-intent-enabled \\\n --renew-intent-redis-dsn \"redis://user:pass@redis:6379/0\" \\\n --renew-intent-min-interval 120\n```\n\n## Build\n```bash\ncd components/ingress\nmake build\n# override build metadata if needed\nVERSION=1.2.3 GIT_COMMIT=$(git rev-parse HEAD) BUILD_TIME=$(date -u +\"%Y-%m-%dT%H:%M:%SZ\") make build\n```\n\n## Docker Build\nDockerfile already wires ldflags via build args:\n```bash\ndocker build \\\n --build-arg VERSION=$(git describe --tags --always --dirty) \\\n --build-arg GIT_COMMIT=$(git rev-parse HEAD) \\\n --build-arg BUILD_TIME=$(date -u +\"%Y-%m-%dT%H:%M:%SZ\") \\\n -t opensandbox/ingress:local .\n```\n\n## Multi-arch Publish Script\n`build.sh` uses buildx to build/push linux/amd64 and linux/arm64:\n```bash\ncd components/ingress\nTAG=local VERSION=1.2.3 GIT_COMMIT=abc BUILD_TIME=2025-01-01T00:00:00Z bash build.sh\n```\n\n## Runtime Requirements\n- Access to Kubernetes API (in-cluster or via KUBECONFIG).\n- If `--provider-type=batchsandbox`: BatchSandbox CRs in the specified Namespace with `sandbox.opensandbox.io/endpoints` annotation containing Pod IPs.\n- If `--provider-type=agent-sandbox`: AgentSandbox CRs with `status.serviceFQDN` populated.\n\n## Implementation Notes\n\n### Header Mode Behavior\n- Routing key priority: `OpenSandbox-Ingress-To` header first, otherwise Host parsing `-.*`.\n- Sandbox name extracted from request is used to query the sandbox CR (BatchSandbox or AgentSandbox) via informer cache:\n - BatchSandbox โ†’ endpoints annotation.\n - AgentSandbox โ†’ `status.serviceFQDN`.\n- The original request path is preserved and forwarded to the target sandbox.\n\n### URI Mode Behavior\n- Routing information is extracted from the URI path: `///`.\n- The sandbox ID and port are extracted from the first two path segments.\n- The remaining path (`/`) is forwarded to the target sandbox as the request URI.\n- If no remaining path is provided, the request URI defaults to `/`.\n\n### Commons\n- Error handling:\n - `ErrSandboxNotFound` (sandbox resource not exists) โ†’ HTTP 404\n - `ErrSandboxNotReady` (not enough replicas, missing endpoints, invalid config) โ†’ HTTP 503\n - Other errors (K8s API errors, etc.) โ†’ HTTP 502\n- WebSocket path forwards essential headers and X-Forwarded-*; HTTP path strips `OpenSandbox-Ingress-To` before proxying (header mode only).\n\n## Development & Tests\n```bash\ncd components/ingress\ngo test ./...\n```\nKey code:\n- `main.go`: entrypoint and handlers.\n- `pkg/proxy/`: HTTP/WebSocket proxy logic, sandbox endpoint resolution.\n- `pkg/sandbox/`: Sandbox provider abstraction and BatchSandbox implementation.\n- `version/`: build metadata output (populated via ldflags).\n\n" }, { "path": "components/ingress/build.sh", "content": "#!/bin/bash\n# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nset -ex\n\nTAG=${TAG:-latest}\nVERSION=${VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo \"dev\")}\nGIT_COMMIT=${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo \"unknown\")}\nBUILD_TIME=${BUILD_TIME:-$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")}\n\nREPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || realpath \"$(dirname \"$0\")/../..\")\ncd \"${REPO_ROOT}\"\n\ndocker buildx rm ingress-builder || true\n\ndocker buildx create --use --name ingress-builder\n\ndocker buildx inspect --bootstrap\n\ndocker buildx ls\n\nLATEST_TAGS=()\nif [[ \"${TAG}\" == v* ]]; then\n LATEST_TAGS+=(-t opensandbox/ingress:latest -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/ingress:latest)\nfi\n\ndocker buildx build \\\n -t opensandbox/ingress:${TAG} \\\n -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/ingress:${TAG} \\\n \"${LATEST_TAGS[@]}\" \\\n -f components/ingress/Dockerfile \\\n --build-arg VERSION=\"${VERSION}\" \\\n --build-arg GIT_COMMIT=\"${GIT_COMMIT}\" \\\n --build-arg BUILD_TIME=\"${BUILD_TIME}\" \\\n --platform linux/amd64,linux/arm64 \\\n --push \\\n .\n" }, { "path": "components/ingress/go.mod", "content": "module github.com/alibaba/opensandbox/ingress\n\ngo 1.24.0\n\nrequire (\n\tgithub.com/alibaba/OpenSandbox/sandbox-k8s v0.0.0\n\tgithub.com/alibaba/opensandbox/internal v0.0.0\n\tgithub.com/alicebob/miniredis/v2 v2.37.0\n\tgithub.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674\n\tgithub.com/redis/go-redis/v9 v9.18.0\n\tgithub.com/stretchr/testify v1.11.1\n\tk8s.io/apimachinery v0.34.3\n\tk8s.io/client-go v0.34.3\n\tknative.dev/pkg v0.0.0-20260120122510-4a022ed9999a\n)\n\nrequire (\n\tgithub.com/blendle/zapdriver v1.3.1 // indirect\n\tgithub.com/cespare/xxhash/v2 v2.3.0 // indirect\n\tgithub.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect\n\tgithub.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect\n\tgithub.com/emicklei/go-restful/v3 v3.12.2 // indirect\n\tgithub.com/evanphx/json-patch/v5 v5.9.11 // indirect\n\tgithub.com/fxamacker/cbor/v2 v2.9.0 // indirect\n\tgithub.com/go-logr/logr v1.4.3 // indirect\n\tgithub.com/go-logr/stdr v1.2.2 // indirect\n\tgithub.com/go-openapi/jsonpointer v0.21.0 // indirect\n\tgithub.com/go-openapi/jsonreference v0.21.0 // indirect\n\tgithub.com/go-openapi/swag v0.23.0 // indirect\n\tgithub.com/gogo/protobuf v1.3.2 // indirect\n\tgithub.com/google/gnostic-models v0.7.0 // indirect\n\tgithub.com/google/go-cmp v0.7.0 // indirect\n\tgithub.com/google/uuid v1.6.0 // indirect\n\tgithub.com/hashicorp/golang-lru v1.0.2 // indirect\n\tgithub.com/josharian/intern v1.0.0 // indirect\n\tgithub.com/json-iterator/go v1.1.12 // indirect\n\tgithub.com/kelseyhightower/envconfig v1.4.0 // indirect\n\tgithub.com/mailru/easyjson v0.9.0 // indirect\n\tgithub.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect\n\tgithub.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect\n\tgithub.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect\n\tgithub.com/pkg/errors v0.9.1 // indirect\n\tgithub.com/pmezard/go-difflib v1.0.0 // indirect\n\tgithub.com/spf13/pflag v1.0.10 // indirect\n\tgithub.com/x448/float16 v0.8.4 // indirect\n\tgithub.com/yuin/gopher-lua v1.1.1 // indirect\n\tgo.opentelemetry.io/auto/sdk v1.2.1 // indirect\n\tgo.opentelemetry.io/otel v1.40.0 // indirect\n\tgo.opentelemetry.io/otel/metric v1.40.0 // indirect\n\tgo.opentelemetry.io/otel/trace v1.40.0 // indirect\n\tgo.uber.org/atomic v1.11.0 // indirect\n\tgo.uber.org/multierr v1.11.0 // indirect\n\tgo.uber.org/zap v1.27.1 // indirect\n\tgo.yaml.in/yaml/v2 v2.4.3 // indirect\n\tgo.yaml.in/yaml/v3 v3.0.4 // indirect\n\tgolang.org/x/net v0.49.0 // indirect\n\tgolang.org/x/oauth2 v0.32.0 // indirect\n\tgolang.org/x/sync v0.19.0 // indirect\n\tgolang.org/x/sys v0.40.0 // indirect\n\tgolang.org/x/term v0.39.0 // indirect\n\tgolang.org/x/text v0.33.0 // indirect\n\tgolang.org/x/time v0.10.0 // indirect\n\tgomodules.xyz/jsonpatch/v2 v2.5.0 // indirect\n\tgoogle.golang.org/protobuf v1.36.10 // indirect\n\tgopkg.in/evanphx/json-patch.v4 v4.12.0 // indirect\n\tgopkg.in/inf.v0 v0.9.1 // indirect\n\tgopkg.in/yaml.v3 v3.0.1 // indirect\n\tk8s.io/api v0.34.3 // indirect\n\tk8s.io/klog/v2 v2.130.1 // indirect\n\tk8s.io/kube-openapi v0.0.0-20250710124328-f3f2b991d03b // indirect\n\tk8s.io/utils v0.0.0-20250604170112-4c0f3b243397 // indirect\n\tsigs.k8s.io/controller-runtime v0.21.0 // indirect\n\tsigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8 // indirect\n\tsigs.k8s.io/randfill v1.0.0 // indirect\n\tsigs.k8s.io/structured-merge-diff/v6 v6.3.0 // indirect\n\tsigs.k8s.io/yaml v1.6.0 // indirect\n)\n\nreplace github.com/alibaba/OpenSandbox/sandbox-k8s => ../../kubernetes\n\nreplace github.com/alibaba/opensandbox/internal => ../internal\n" }, { "path": "components/ingress/go.sum", "content": "github.com/alicebob/miniredis/v2 v2.37.0 h1:RheObYW32G1aiJIj81XVt78ZHJpHonHLHW7OLIshq68=\ngithub.com/alicebob/miniredis/v2 v2.37.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM=\ngithub.com/blendle/zapdriver v1.3.1 h1:C3dydBOWYRiOk+B8X9IVZ5IOe+7cl+tGOexN4QqHfpE=\ngithub.com/blendle/zapdriver v1.3.1/go.mod h1:mdXfREi6u5MArG4j9fewC+FGnXaBR+T4Ox4J2u4eHCc=\ngithub.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=\ngithub.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=\ngithub.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=\ngithub.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=\ngithub.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=\ngithub.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=\ngithub.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=\ngithub.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=\ngithub.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=\ngithub.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=\ngithub.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=\ngithub.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=\ngithub.com/emicklei/go-restful/v3 v3.12.2 h1:DhwDP0vY3k8ZzE0RunuJy8GhNpPL6zqLkDf9B/a0/xU=\ngithub.com/emicklei/go-restful/v3 v3.12.2/go.mod h1:6n3XBCmQQb25CM2LCACGz8ukIrRry+4bhvbpWn3mrbc=\ngithub.com/evanphx/json-patch v5.9.0+incompatible h1:fBXyNpNMuTTDdquAq/uisOr2lShz4oaXpDTX2bLe7ls=\ngithub.com/evanphx/json-patch v5.9.0+incompatible/go.mod h1:50XU6AFN0ol/bzJsmQLiYLvXMP4fmwYFNcr97nuDLSk=\ngithub.com/evanphx/json-patch/v5 v5.9.11 h1:/8HVnzMq13/3x9TPvjG08wUGqBTmZBsCWzjTM0wiaDU=\ngithub.com/evanphx/json-patch/v5 v5.9.11/go.mod h1:3j+LviiESTElxA4p3EMKAB9HXj3/XEtnUf6OZxqIQTM=\ngithub.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=\ngithub.com/fxamacker/cbor/v2 v2.9.0/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=\ngithub.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=\ngithub.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=\ngithub.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=\ngithub.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=\ngithub.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=\ngithub.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ=\ngithub.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY=\ngithub.com/go-openapi/jsonreference v0.21.0 h1:Rs+Y7hSXT83Jacb7kFyjn4ijOuVGSvOdF2+tg1TRrwQ=\ngithub.com/go-openapi/jsonreference v0.21.0/go.mod h1:LmZmgsrTkVg9LG4EaHeY8cBDslNPMo06cago5JNLkm4=\ngithub.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE=\ngithub.com/go-openapi/swag v0.23.0/go.mod h1:esZ8ITTYEsH1V2trKHjAN8Ai7xHb8RV+YSZ577vPjgQ=\ngithub.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=\ngithub.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=\ngithub.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=\ngithub.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=\ngithub.com/google/gnostic-models v0.7.0 h1:qwTtogB15McXDaNqTZdzPJRHvaVJlAl+HVQnLmJEJxo=\ngithub.com/google/gnostic-models v0.7.0/go.mod h1:whL5G0m6dmc5cPxKc5bdKdEN3UjI7OUGxBlw57miDrQ=\ngithub.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=\ngithub.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=\ngithub.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=\ngithub.com/google/pprof v0.0.0-20241029153458-d1b30febd7db h1:097atOisP2aRj7vFgYQBbFN4U4JNXUNYpxael3UzMyo=\ngithub.com/google/pprof v0.0.0-20241029153458-d1b30febd7db/go.mod h1:vavhavw2zAxS5dIdcRluK6cSGGPlZynqzFM8NdvU144=\ngithub.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=\ngithub.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=\ngithub.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5THxAzdVpqr6/geYxZytqFMBCOtn/ujyeo=\ngithub.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=\ngithub.com/hashicorp/golang-lru v1.0.2 h1:dV3g9Z/unq5DpblPpw+Oqcv4dU/1omnb4Ok8iPY6p1c=\ngithub.com/hashicorp/golang-lru v1.0.2/go.mod h1:iADmTwqILo4mZ8BN3D2Q6+9jd8WM5uGBxy+E8yxSoD4=\ngithub.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=\ngithub.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=\ngithub.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=\ngithub.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=\ngithub.com/kelseyhightower/envconfig v1.4.0 h1:Im6hONhd3pLkfDFsbRgu68RDNkGF1r3dvMUtDTo2cv8=\ngithub.com/kelseyhightower/envconfig v1.4.0/go.mod h1:cccZRl6mQpaq41TPp5QxidR+Sa3axMbJDNb//FQX6Gg=\ngithub.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=\ngithub.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=\ngithub.com/klauspost/cpuid/v2 v2.0.9 h1:lgaqFMSdTdQYdZ04uHyN2d/eKdOMyi2YLSvlQIBFYa4=\ngithub.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=\ngithub.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=\ngithub.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=\ngithub.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=\ngithub.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=\ngithub.com/mailru/easyjson v0.9.0 h1:PrnmzHw7262yW8sTBwxi1PdJA3Iw/EKBa8psRf7d9a4=\ngithub.com/mailru/easyjson v0.9.0/go.mod h1:1+xMtQp2MRNVL/V1bOzuP3aP8VNwRW55fQUto+XFtTU=\ngithub.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=\ngithub.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=\ngithub.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=\ngithub.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=\ngithub.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee h1:W5t00kpgFdJifH4BDsTlE89Zl93FEloxaWZfGcifgq8=\ngithub.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=\ngithub.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=\ngithub.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=\ngithub.com/onsi/ginkgo/v2 v2.22.0 h1:Yed107/8DjTr0lKCNt7Dn8yQ6ybuDRQoMGrNFKzMfHg=\ngithub.com/onsi/ginkgo/v2 v2.22.0/go.mod h1:7Du3c42kxCUegi0IImZ1wUQzMBVecgIHjR1C+NkhLQo=\ngithub.com/onsi/gomega v1.36.1 h1:bJDPBO7ibjxcbHMgSCoo4Yj18UWbKDlLwX1x9sybDcw=\ngithub.com/onsi/gomega v1.36.1/go.mod h1:PvZbdDc8J6XJEpDK4HCuRBm8a6Fzp9/DmhC9C7yFlog=\ngithub.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=\ngithub.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=\ngithub.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=\ngithub.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=\ngithub.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=\ngithub.com/redis/go-redis/v9 v9.18.0 h1:pMkxYPkEbMPwRdenAzUNyFNrDgHx9U+DrBabWNfSRQs=\ngithub.com/redis/go-redis/v9 v9.18.0/go.mod h1:k3ufPphLU5YXwNTUcCRXGxUoF1fqxnhFQmscfkCoDA0=\ngithub.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=\ngithub.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=\ngithub.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=\ngithub.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=\ngithub.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=\ngithub.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=\ngithub.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=\ngithub.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=\ngithub.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=\ngithub.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=\ngithub.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=\ngithub.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=\ngithub.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=\ngithub.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=\ngithub.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=\ngithub.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw=\ngithub.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=\ngithub.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=\ngo.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=\ngo.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=\ngo.opentelemetry.io/otel v1.40.0 h1:oA5YeOcpRTXq6NN7frwmwFR0Cn3RhTVZvXsP4duvCms=\ngo.opentelemetry.io/otel v1.40.0/go.mod h1:IMb+uXZUKkMXdPddhwAHm6UfOwJyh4ct1ybIlV14J0g=\ngo.opentelemetry.io/otel/metric v1.40.0 h1:rcZe317KPftE2rstWIBitCdVp89A2HqjkxR3c11+p9g=\ngo.opentelemetry.io/otel/metric v1.40.0/go.mod h1:ib/crwQH7N3r5kfiBZQbwrTge743UDc7DTFVZrrXnqc=\ngo.opentelemetry.io/otel/sdk v1.40.0 h1:KHW/jUzgo6wsPh9At46+h4upjtccTmuZCFAc9OJ71f8=\ngo.opentelemetry.io/otel/sdk v1.40.0/go.mod h1:Ph7EFdYvxq72Y8Li9q8KebuYUr2KoeyHx0DRMKrYBUE=\ngo.opentelemetry.io/otel/sdk/metric v1.39.0 h1:cXMVVFVgsIf2YL6QkRF4Urbr/aMInf+2WKg+sEJTtB8=\ngo.opentelemetry.io/otel/sdk/metric v1.39.0/go.mod h1:xq9HEVH7qeX69/JnwEfp6fVq5wosJsY1mt4lLfYdVew=\ngo.opentelemetry.io/otel/trace v1.40.0 h1:WA4etStDttCSYuhwvEa8OP8I5EWu24lkOzp+ZYblVjw=\ngo.opentelemetry.io/otel/trace v1.40.0/go.mod h1:zeAhriXecNGP/s2SEG3+Y8X9ujcJOTqQ5RgdEJcawiA=\ngo.uber.org/atomic v1.4.0/go.mod h1:gD2HeocX3+yG+ygLZcrzQJaqmWj9AIm7n08wl/qW/PE=\ngo.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=\ngo.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=\ngo.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=\ngo.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=\ngo.uber.org/multierr v1.1.0/go.mod h1:wR5kodmAFQ0UK8QlbwjlSNy0Z68gJhDJUG5sjR94q/0=\ngo.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=\ngo.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=\ngo.uber.org/zap v1.10.0/go.mod h1:vwi/ZaCAaUcBkycHslxD9B2zi4UTXhF60s6SWpuDF0Q=\ngo.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=\ngo.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=\ngo.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=\ngo.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=\ngo.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=\ngo.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=\ngolang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=\ngolang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=\ngolang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=\ngolang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=\ngolang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=\ngolang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=\ngolang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=\ngolang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=\ngolang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=\ngolang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=\ngolang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=\ngolang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=\ngolang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=\ngolang.org/x/oauth2 v0.32.0 h1:jsCblLleRMDrxMN29H3z/k1KliIvpLgCkE6R8FXXNgY=\ngolang.org/x/oauth2 v0.32.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=\ngolang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=\ngolang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=\ngolang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=\ngolang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=\ngolang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=\ngolang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=\ngolang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=\ngolang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=\ngolang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=\ngolang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=\ngolang.org/x/term v0.39.0 h1:RclSuaJf32jOqZz74CkPA9qFuVTX7vhLlpfj/IGWlqY=\ngolang.org/x/term v0.39.0/go.mod h1:yxzUCTP/U+FzoxfdKmLaA0RV1WgE0VY7hXBwKtY/4ww=\ngolang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=\ngolang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=\ngolang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=\ngolang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=\ngolang.org/x/time v0.10.0 h1:3usCWA8tQn0L8+hFJQNgzpWbd89begxN66o1Ojdn5L4=\ngolang.org/x/time v0.10.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=\ngolang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=\ngolang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=\ngolang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=\ngolang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=\ngolang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=\ngolang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=\ngolang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=\ngolang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=\ngolang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=\ngolang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=\ngomodules.xyz/jsonpatch/v2 v2.5.0 h1:JELs8RLM12qJGXU4u/TO3V25KW8GreMKl9pdkk14RM0=\ngomodules.xyz/jsonpatch/v2 v2.5.0/go.mod h1:AH3dM2RI6uoBZxn3LVrfvJ3E0/9dG4cSrbuBJT4moAY=\ngoogle.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=\ngoogle.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=\ngopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=\ngopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=\ngopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=\ngopkg.in/evanphx/json-patch.v4 v4.12.0 h1:n6jtcsulIzXPJaxegRbvFNNrZDjbij7ny3gmSPG+6V4=\ngopkg.in/evanphx/json-patch.v4 v4.12.0/go.mod h1:p8EYWUEYMpynmqDbY58zCKCFZw8pRWMG4EsWvDvM72M=\ngopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=\ngopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=\ngopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=\ngopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=\nk8s.io/api v0.34.3 h1:D12sTP257/jSH2vHV2EDYrb16bS7ULlHpdNdNhEw2S4=\nk8s.io/api v0.34.3/go.mod h1:PyVQBF886Q5RSQZOim7DybQjAbVs8g7gwJNhGtY5MBk=\nk8s.io/apimachinery v0.34.3 h1:/TB+SFEiQvN9HPldtlWOTp0hWbJ+fjU+wkxysf/aQnE=\nk8s.io/apimachinery v0.34.3/go.mod h1:/GwIlEcWuTX9zKIg2mbw0LRFIsXwrfoVxn+ef0X13lw=\nk8s.io/client-go v0.34.3 h1:wtYtpzy/OPNYf7WyNBTj3iUA0XaBHVqhv4Iv3tbrF5A=\nk8s.io/client-go v0.34.3/go.mod h1:OxxeYagaP9Kdf78UrKLa3YZixMCfP6bgPwPwNBQBzpM=\nk8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=\nk8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=\nk8s.io/kube-openapi v0.0.0-20250710124328-f3f2b991d03b h1:MloQ9/bdJyIu9lb1PzujOPolHyvO06MXG5TUIj2mNAA=\nk8s.io/kube-openapi v0.0.0-20250710124328-f3f2b991d03b/go.mod h1:UZ2yyWbFTpuhSbFhv24aGNOdoRdJZgsIObGBUaYVsts=\nk8s.io/utils v0.0.0-20250604170112-4c0f3b243397 h1:hwvWFiBzdWw1FhfY1FooPn3kzWuJ8tmbZBHi4zVsl1Y=\nk8s.io/utils v0.0.0-20250604170112-4c0f3b243397/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=\nknative.dev/pkg v0.0.0-20260120122510-4a022ed9999a h1:9f29OTA7w/iVIX6PS6yveVVzNbcUS74eQfchVe8o2/4=\nknative.dev/pkg v0.0.0-20260120122510-4a022ed9999a/go.mod h1:Tz3GoxcNC5vH3Zo//cW3mnHL474u+Y1wbsUIZ11p8No=\nsigs.k8s.io/controller-runtime v0.21.0 h1:CYfjpEuicjUecRk+KAeyYh+ouUBn4llGyDYytIGcJS8=\nsigs.k8s.io/controller-runtime v0.21.0/go.mod h1:OSg14+F65eWqIu4DceX7k/+QRAbTTvxeQSNSOQpukWM=\nsigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8 h1:gBQPwqORJ8d8/YNZWEjoZs7npUVDpVXUUOFfW6CgAqE=\nsigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8/go.mod h1:mdzfpAEoE6DHQEN0uh9ZbOCuHbLK5wOm7dK4ctXE9Tg=\nsigs.k8s.io/randfill v1.0.0 h1:JfjMILfT8A6RbawdsK2JXGBR5AQVfd+9TbzrlneTyrU=\nsigs.k8s.io/randfill v1.0.0/go.mod h1:XeLlZ/jmk4i1HRopwe7/aU3H5n1zNUcX6TM94b3QxOY=\nsigs.k8s.io/structured-merge-diff/v6 v6.3.0 h1:jTijUJbW353oVOd9oTlifJqOGEkUw2jB/fXCbTiQEco=\nsigs.k8s.io/structured-merge-diff/v6 v6.3.0/go.mod h1:M3W8sfWvn2HhQDIbGWj3S099YozAsymCo/wrT5ohRUE=\nsigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=\nsigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=\n" }, { "path": "components/ingress/main.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"net/http\"\n\t\"time\"\n\n\t\"k8s.io/apimachinery/pkg/runtime\"\n\t\"knative.dev/pkg/injection\"\n\t\"knative.dev/pkg/signals\"\n\n\t\"github.com/alibaba/opensandbox/ingress/pkg/flag\"\n\t\"github.com/alibaba/opensandbox/ingress/pkg/proxy\"\n\t\"github.com/alibaba/opensandbox/ingress/pkg/renewintent\"\n\t\"github.com/alibaba/opensandbox/ingress/pkg/sandbox\"\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n\t\"github.com/alibaba/opensandbox/internal/version\"\n)\n\nfunc main() {\n\tversion.EchoVersion(\"OpenSandbox Ingress\")\n\n\tflag.InitFlags()\n\tif flag.Namespace == \"\" {\n\t\tlog.Panicf(\"'-namespace' not set.\")\n\t}\n\n\tcfg := injection.ParseAndGetRESTConfigOrDie()\n\tcfg.ContentType = runtime.ContentTypeProtobuf\n\tcfg.UserAgent = \"opensandbox-ingress/\" + version.GitCommit\n\n\tctx := signals.NewContext()\n\tctx = withLogger(ctx, flag.LogLevel)\n\n\t// Create sandbox provider factory\n\tproviderFactory := sandbox.NewProviderFactory(\n\t\tcfg,\n\t\tflag.Namespace,\n\t\ttime.Second*30, // resync period\n\t)\n\n\t// Create sandbox provider based on provider type\n\tsandboxProvider, err := providerFactory.CreateProvider(sandbox.ProviderType(flag.ProviderType))\n\tif err != nil {\n\t\tlog.Panicf(\"Failed to create sandbox provider: %v\", err)\n\t}\n\n\t// Start provider (includes cache sync)\n\tif err := sandboxProvider.Start(ctx); err != nil {\n\t\tlog.Panicf(\"Failed to start sandbox provider: %v\", err)\n\t}\n\n\tvar renewPublisher renewintent.Publisher\n\tif flag.RenewIntentEnabled {\n\t\tredisClient, err := renewintent.RedisClientFromDSN(flag.RenewIntentRedisDSN)\n\t\tif err != nil {\n\t\t\tlog.Panicf(\"Failed to create Redis client for renew-intent: %v\", err)\n\t\t}\n\t\trenewPublisher = renewintent.NewRedisPublisher(ctx, redisClient, renewintent.RedisPublisherConfig{\n\t\t\tQueueKey: flag.RenewIntentQueueKey,\n\t\t\tQueueMaxLen: flag.RenewIntentQueueMaxLen,\n\t\t\tMinInterval: time.Duration(flag.RenewIntentMinIntervalSec) * time.Second,\n\t\t\tLogger: proxy.Logger,\n\t\t})\n\t}\n\n\t// Create reverse proxy with sandbox provider\n\treverseProxy := proxy.NewProxy(ctx, sandboxProvider, proxy.Mode(flag.Mode), renewPublisher)\n\thttp.Handle(\"/\", reverseProxy)\n\thttp.HandleFunc(\"/status.ok\", proxy.Healthz)\n\n\tif err := http.ListenAndServe(fmt.Sprintf(\":%v\", flag.Port), nil); err != nil {\n\t\tlog.Panicf(\"Error starting http server: %v\", err)\n\t}\n\n\tpanic(\"unreachable\")\n}\n\nfunc withLogger(ctx context.Context, logLevel string) context.Context {\n\tlogger := slogger.MustNew(slogger.Config{Level: logLevel}).Named(\"opensandbox.ingress\")\n\treturn proxy.WithLogger(ctx, logger)\n}\n" }, { "path": "components/ingress/pkg/flag/flags.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage flag\n\nvar (\n\t// LogLevel controls the router log verbosity.\n\tLogLevel string\n\n\t// Port controls the HTTP listener port.\n\tPort int\n\n\t// Namespace filters the target sandbox instances.\n\tNamespace string\n\n\t// ProviderType specifies the sandbox provider type (e.g., batchsandbox).\n\tProviderType string\n\n\t// Mode specifies the sandbox service discovery mode (e.g., header, uri).\n\tMode string\n\n\tRenewIntentEnabled bool\n\tRenewIntentRedisDSN string\n\tRenewIntentQueueKey string\n\tRenewIntentQueueMaxLen int\n\tRenewIntentMinIntervalSec int\n)\n" }, { "path": "components/ingress/pkg/flag/parser.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage flag\n\nimport (\n\t\"flag\"\n)\n\nfunc InitFlags() {\n\tflag.StringVar(&LogLevel, \"log-level\", \"info\", \"Server log level\")\n\tflag.IntVar(&Port, \"port\", 28888, \"Server listening port (default: 28888)\")\n\tflag.StringVar(&Namespace, \"namespace\", \"opensandbox\", \"The Kubernetes namespace to watch for sandbox resources\")\n\tflag.StringVar(&ProviderType, \"provider-type\", \"batchsandbox\", \"The sandbox provider type (default: batchsandbox)\")\n\tflag.StringVar(&Mode, \"mode\", \"header\", \"The sandbox service discovery mode (default: header)\")\n\n\tflag.BoolVar(&RenewIntentEnabled, \"renew-intent-enabled\", false, \"Enable publishing renew-intent events to Redis (OSEP-0009)\")\n\tflag.StringVar(&RenewIntentRedisDSN, \"renew-intent-redis-dsn\", \"redis://127.0.0.1:6379/0\", \"Redis DSN for renew-intent queue\")\n\tflag.StringVar(&RenewIntentQueueKey, \"renew-intent-queue-key\", \"opensandbox:renew:intent\", \"Redis List key for renew-intent payloads\")\n\tflag.IntVar(&RenewIntentQueueMaxLen, \"renew-intent-queue-max-len\", 0, \"Max renew-intent queue length (0 = no cap)\")\n\tflag.IntVar(&RenewIntentMinIntervalSec, \"renew-intent-min-interval\", 60, \"Min seconds between publishing intents for the same sandbox (client-side throttle)\")\n\n\tflag.Parse()\n}\n" }, { "path": "components/ingress/pkg/proxy/header.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport \"net/http\"\n\nvar (\n\tXRealIP = http.CanonicalHeaderKey(\"X-Real-IP\")\n\tXForwardedFor = http.CanonicalHeaderKey(\"X-Forwarded-For\")\n\tXForwardedProto = http.CanonicalHeaderKey(\"X-Forwarded-Proto\")\n\n\tSandboxIngress = http.CanonicalHeaderKey(\"OpenSandbox-Ingress-To\")\n\t// DeprecatedSandboxIngress is the deprecated header name\n\t// Deprecated\n\tDeprecatedSandboxIngress = http.CanonicalHeaderKey(\"OPEN-SANDBOX-INGRESS\")\n\n\tAccessControlAllowOrigin = http.CanonicalHeaderKey(\"Access-Control-Allow-Origin\")\n\tReverseProxyServerPowerBy = http.CanonicalHeaderKey(\"Reverse-Proxy-Server-PowerBy\")\n\n\tSecWebSocketProtocol = http.CanonicalHeaderKey(\"Sec-WebSocket-Protocol\")\n\tCookie = http.CanonicalHeaderKey(\"Cookie\")\n\tSetCookie = http.CanonicalHeaderKey(\"Set-Cookie\")\n\tHost = http.CanonicalHeaderKey(\"Host\")\n\tOrigin = http.CanonicalHeaderKey(\"Origin\")\n)\n" }, { "path": "components/ingress/pkg/proxy/healthz.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport \"net/http\"\n\nfunc Healthz(w http.ResponseWriter, _ *http.Request) {\n\tw.WriteHeader(http.StatusOK)\n\t_, _ = w.Write([]byte(\"OK\"))\n}\n" }, { "path": "components/ingress/pkg/proxy/healthz_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"testing\"\n\n\t\"github.com/stretchr/testify/assert\"\n)\n\nfunc TestHealthz(t *testing.T) {\n\treq := httptest.NewRequest(http.MethodGet, \"/healthz\", nil)\n\trr := httptest.NewRecorder()\n\n\tHealthz(rr, req)\n\n\tassert.Equal(t, http.StatusOK, rr.Code)\n\tassert.Equal(t, \"OK\", rr.Body.String())\n}\n" }, { "path": "components/ingress/pkg/proxy/host.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"strconv\"\n\t\"strings\"\n)\n\ntype Mode string\n\nconst (\n\t// ModeHeader is the mode that uses the Host or SandboxIngress header\n\t// to determine the sandbox instance.\n\tModeHeader Mode = \"header\"\n\n\t// ModeURI is the mode that uses the URI path to determine the\n\t// sandbox instance.\n\t//\n\t// Pattern is 'hostname///'.\n\tModeURI Mode = \"uri\"\n)\n\nfunc (p *Proxy) getSandboxHostDefinition(r *http.Request) (*sandboxHost, error) {\n\tswitch p.mode {\n\tcase ModeHeader:\n\t\ttargetHost := p.parseTargetHostByHeader(r)\n\t\tif targetHost == \"\" {\n\t\t\treturn nil, fmt.Errorf(\"missing header '%s' or 'Host'\", SandboxIngress)\n\t\t}\n\n\t\thost, err := p.parseSandboxHost(targetHost)\n\t\tif err != nil || host.ingressKey == \"\" || host.port == 0 {\n\t\t\treturn nil, fmt.Errorf(\"invalid host: %s\", targetHost)\n\t\t}\n\t\treturn host, nil\n\tcase ModeURI:\n\t\treturn p.parseSandboxURI(r)\n\t}\n\n\treturn nil, fmt.Errorf(\"unknown ingress mode: %s\", p.mode)\n}\n\nfunc (p *Proxy) parseTargetHostByHeader(r *http.Request) string {\n\ttargetHost := r.Header.Get(SandboxIngress)\n\tif targetHost != \"\" {\n\t\treturn targetHost\n\t}\n\tdeprecatedTargetHost := r.Header.Get(DeprecatedSandboxIngress)\n\tif deprecatedTargetHost != \"\" {\n\t\treturn deprecatedTargetHost\n\t}\n\n\treturn r.Host\n}\n\ntype sandboxHost struct {\n\tingressKey string\n\tport int\n\trequestURI string\n}\n\nfunc (p *Proxy) parseSandboxHost(s string) (*sandboxHost, error) {\n\tdomain := strings.Split(strings.TrimPrefix(strings.TrimPrefix(s, \"https://\"), \"http://\"), \".\")\n\tif len(domain) < 1 {\n\t\treturn &sandboxHost{}, fmt.Errorf(\"invalid host: %s\", s)\n\t}\n\n\tingressAndPort := strings.Split(domain[0], \"-\")\n\tif len(ingressAndPort) <= 1 || ingressAndPort[0] == \"\" {\n\t\treturn &sandboxHost{}, fmt.Errorf(\"invalid host: %s\", s)\n\t}\n\n\tingress := strings.Join(ingressAndPort[:len(ingressAndPort)-1], \"-\")\n\tport, err := strconv.Atoi(ingressAndPort[len(ingressAndPort)-1])\n\tif err != nil {\n\t\treturn &sandboxHost{}, fmt.Errorf(\"invalid port format: %w\", err)\n\t}\n\treturn &sandboxHost{ingress, port, \"\"}, nil\n}\n\nfunc (p *Proxy) parseSandboxURI(r *http.Request) (*sandboxHost, error) {\n\tpath := r.URL.Path\n\tif path == \"\" {\n\t\treturn nil, errors.New(\"missing URI path\")\n\t}\n\n\t// Remove leading slash and split by '/'\n\tpath = strings.TrimPrefix(path, \"/\")\n\tparts := strings.SplitN(path, \"/\", 3)\n\tif len(parts) < 2 {\n\t\treturn nil, fmt.Errorf(\"invalid URI path format: expected '///', got: %s\", r.URL.Path)\n\t}\n\n\tsandboxID := parts[0]\n\tport, err := strconv.Atoi(parts[1])\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"invalid port format: %w\", err)\n\t}\n\tif sandboxID == \"\" || port <= 0 {\n\t\treturn nil, errors.New(\"missing sandbox-id or sandbox-port in URI path\")\n\t}\n\n\t// Extract the remaining path (user's target request URI)\n\tvar requestURI string\n\tif len(parts) >= 3 && parts[2] != \"\" {\n\t\trequestURI = \"/\" + parts[2]\n\t} else {\n\t\trequestURI = \"/\"\n\t}\n\n\treturn &sandboxHost{\n\t\tingressKey: sandboxID,\n\t\tport: port,\n\t\trequestURI: requestURI,\n\t}, nil\n}\n" }, { "path": "components/ingress/pkg/proxy/http.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"net/http\"\n\t\"net/http/httputil\"\n\t\"net/url\"\n)\n\ntype HTTPProxy struct{}\n\nfunc NewHTTPProxy() *HTTPProxy {\n\treturn &HTTPProxy{}\n}\n\nfunc (hp *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {\n\ttargetURL := r.URL.String()\n\n\tproxy, err := hp.newReverseProxy(targetURL)\n\tif err != nil {\n\t\thttp.Error(w, err.Error(), http.StatusBadGateway)\n\t\treturn\n\t}\n\n\tproxy.ServeHTTP(w, r)\n}\n\nfunc (hp *HTTPProxy) newReverseProxy(targetHost string) (*httputil.ReverseProxy, error) {\n\turl, err := url.Parse(targetHost)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tproxy := httputil.NewSingleHostReverseProxy(url)\n\tproxy.Director = func(req *http.Request) {\n\t\treq.URL.Scheme = url.Scheme\n\t\treq.URL.Host = url.Host\n\t\treq.Host = url.Host\n\t\treq.Header.Del(SandboxIngress)\n\t}\n\tproxy.ModifyResponse = func(response *http.Response) error {\n\t\tresponse.Header.Add(ReverseProxyServerPowerBy, \"OpenSandbox-ingress\")\n\t\treturn nil\n\t}\n\treturn proxy, nil\n}\n" }, { "path": "components/ingress/pkg/proxy/http_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"strconv\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/ingress/pkg/sandbox\"\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n\t\"github.com/stretchr/testify/assert\"\n)\n\n// mockProvider implements sandbox.Provider interface for testing\ntype mockProvider struct {\n\tendpoints map[string]string // sandboxName -> IP\n\tnotReady map[string]bool // sandboxName -> notReady flag\n}\n\nfunc (m *mockProvider) GetEndpoint(sandboxId string) (string, error) {\n\tif m.notReady != nil && m.notReady[sandboxId] {\n\t\treturn \"\", fmt.Errorf(\"%w: %s\", sandbox.ErrSandboxNotReady, sandboxId)\n\t}\n\tif ip, ok := m.endpoints[sandboxId]; ok {\n\t\treturn ip, nil\n\t}\n\treturn \"\", fmt.Errorf(\"%w: %s\", sandbox.ErrSandboxNotFound, sandboxId)\n}\n\nfunc (m *mockProvider) Start(_ context.Context) error {\n\treturn nil\n}\n\nfunc Test_HTTPProxy(t *testing.T) {\n\tt.Run(\"with header mode\", func(t *testing.T) {\n\t\thttpProxyWithHeaderMode(t)\n\t})\n\n\tt.Run(\"with uri mode\", func(t *testing.T) {\n\t\thttpProxyWithURIMode(t)\n\t})\n}\n\nfunc httpProxyWithHeaderMode(t *testing.T) {\n\tserver := httptest.NewServer(http.HandlerFunc(realBackendHTTPHandler))\n\tdefer server.Close()\n\tserverPort := server.URL[len(\"http://127.0.0.1:\"):]\n\n\t// Create mock provider with sandbox endpoint\n\tprovider := &mockProvider{\n\t\tendpoints: map[string]string{\n\t\t\t\"test-sandbox\": \"127.0.0.1\",\n\t\t},\n\t}\n\n\tctx := context.Background()\n\tLogger = slogger.MustNew(slogger.Config{Level: \"debug\"})\n\tproxy := NewProxy(ctx, provider, ModeHeader, nil)\n\n\tmux := http.NewServeMux()\n\tmux.Handle(\"/\", proxy)\n\tport, err := findAvailablePort()\n\tassert.Nil(t, err)\n\n\tgo func() {\n\t\tassert.NoError(t, http.ListenAndServe(\":\"+strconv.Itoa(port), mux))\n\t}()\n\n\ttime.Sleep(2 * time.Second)\n\n\t// no header\n\trequest, err := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf(\"http://127.0.0.1:%v/hello\", port), nil)\n\tassert.Nil(t, err)\n\tresponse, err := http.DefaultClient.Do(request)\n\tassert.Nil(t, err)\n\tassert.Equal(t, http.StatusBadRequest, response.StatusCode)\n\tbytes, _ := io.ReadAll(response.Body)\n\tt.Log(string(bytes))\n\n\t// no sandbox backend\n\trequest, err = http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf(\"http://127.0.0.1:%v/hello\", port), nil)\n\trequest.Header.Set(SandboxIngress, fmt.Sprintf(\"non-existent-%v\", port))\n\tresponse, err = http.DefaultClient.Do(request)\n\tassert.Nil(t, err)\n\tassert.Equal(t, http.StatusNotFound, response.StatusCode) // ErrSandboxNotFound -> 404\n\tbytes, _ = io.ReadAll(response.Body)\n\tt.Log(string(bytes))\n\n\t// valid sandbox request\n\trequest, err = http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf(\"http://127.0.0.1:%v/hello?a=1&b=2\", port), nil)\n\tassert.Nil(t, err)\n\n\trequest.Header.Set(SandboxIngress, fmt.Sprintf(\"test-sandbox-%v\", serverPort))\n\tresponse, err = http.DefaultClient.Do(request)\n\tassert.Nil(t, err)\n\tif response.StatusCode != http.StatusOK {\n\t\tbytes, err := io.ReadAll(response.Body)\n\t\tassert.Nil(t, err)\n\t\tt.Log(string(bytes))\n\t}\n\tassert.Equal(t, http.StatusOK, response.StatusCode)\n\n\t// Compatible Host parsing for reverse proxy mode\n\trequest, err = http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf(\"http://127.0.0.1:%v/hello?a=1&b=2\", port), nil)\n\tassert.Nil(t, err)\n\n\trequest.Host = fmt.Sprintf(\"test-sandbox-%v.sandbox.alibaba-inc.com\", serverPort)\n\tresponse, err = http.DefaultClient.Do(request)\n\tassert.Nil(t, err)\n\tif response.StatusCode != http.StatusOK {\n\t\tbytes, err := io.ReadAll(response.Body)\n\t\tassert.Nil(t, err)\n\t\tt.Log(string(bytes))\n\t}\n\tassert.Equal(t, http.StatusOK, response.StatusCode)\n}\n\nfunc httpProxyWithURIMode(t *testing.T) {\n\tserver := httptest.NewServer(http.HandlerFunc(realBackendHTTPHandler))\n\tdefer server.Close()\n\tserverPort := server.URL[len(\"http://127.0.0.1:\"):]\n\n\t// Create mock provider with sandbox endpoint\n\tprovider := &mockProvider{\n\t\tendpoints: map[string]string{\n\t\t\t\"test-sandbox\": \"127.0.0.1\",\n\t\t},\n\t}\n\n\tctx := context.Background()\n\tLogger = slogger.MustNew(slogger.Config{Level: \"debug\"})\n\tproxy := NewProxy(ctx, provider, ModeURI, nil)\n\n\tmux := http.NewServeMux()\n\tmux.Handle(\"/\", proxy)\n\tport, err := findAvailablePort()\n\tassert.Nil(t, err)\n\n\tgo func() {\n\t\tassert.NoError(t, http.ListenAndServe(\":\"+strconv.Itoa(port), mux))\n\t}()\n\n\ttime.Sleep(2 * time.Second)\n\n\t// uri is empty\n\trequest, err := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf(\"http://127.0.0.1:%v\", port), nil)\n\tassert.Nil(t, err)\n\tresponse, err := http.DefaultClient.Do(request)\n\tassert.Nil(t, err)\n\tassert.Equal(t, http.StatusBadRequest, response.StatusCode)\n\tbytes, _ := io.ReadAll(response.Body)\n\tt.Log(string(bytes))\n\n\t// no sandbox backend\n\trequest, err = http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf(\"http://127.0.0.1:%v/non-existent-xxx/80/hello\", port), nil)\n\tresponse, err = http.DefaultClient.Do(request)\n\tassert.Nil(t, err)\n\tassert.Equal(t, http.StatusNotFound, response.StatusCode) // ErrSandboxNotFound -> 404\n\tbytes, _ = io.ReadAll(response.Body)\n\tt.Log(string(bytes))\n\n\t// valid sandbox request\n\trequest, err = http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf(\"http://127.0.0.1:%v/test-sandbox/%v/hello?a=1&b=2\", port, serverPort), nil)\n\tassert.Nil(t, err)\n\tresponse, err = http.DefaultClient.Do(request)\n\tassert.Nil(t, err)\n\tif response.StatusCode != http.StatusOK {\n\t\tbytes, err := io.ReadAll(response.Body)\n\t\tassert.Nil(t, err)\n\t\tt.Log(string(bytes))\n\t}\n\tassert.Equal(t, http.StatusOK, response.StatusCode)\n}\n\nfunc realBackendHTTPHandler(w http.ResponseWriter, r *http.Request) {\n\tif r.Method != http.MethodGet {\n\t\thttp.Error(w, http.StatusText(http.StatusMethodNotAllowed), http.StatusMethodNotAllowed)\n\t\treturn\n\t}\n\n\tif r.URL.Path != \"/hello\" {\n\t\thttp.Error(w, fmt.Sprintf(\"path is not /hello, but %s\", r.URL.Path), http.StatusBadRequest)\n\t}\n\tif r.URL.RawQuery != \"a=1&b=2\" {\n\t\thttp.Error(w, fmt.Sprintf(\"query is not a=1&b=2, but %s\", r.URL.RawQuery), http.StatusBadRequest)\n\t}\n\n\tw.WriteHeader(http.StatusOK)\n\t_, _ = w.Write([]byte(\"hello world\"))\n}\n" }, { "path": "components/ingress/pkg/proxy/logger.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"context\"\n\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n)\n\nvar Logger slogger.Logger\n\nfunc WithLogger(ctx context.Context, logger slogger.Logger) context.Context {\n\tLogger = logger\n\treturn ctx\n}\n" }, { "path": "components/ingress/pkg/proxy/proxy.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"net\"\n\t\"net/http\"\n\t\"strings\"\n\n\t\"github.com/alibaba/opensandbox/ingress/pkg/renewintent\"\n\t\"github.com/alibaba/opensandbox/ingress/pkg/sandbox\"\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n)\n\ntype Proxy struct {\n\tsandboxProvider sandbox.Provider\n\tmode Mode\n\trenewIntentPublisher renewintent.Publisher\n}\n\nfunc NewProxy(_ context.Context, sandboxProvider sandbox.Provider, mode Mode, renewIntentPublisher renewintent.Publisher) *Proxy {\n\treturn &Proxy{\n\t\tsandboxProvider: sandboxProvider,\n\t\tmode: mode,\n\t\trenewIntentPublisher: renewIntentPublisher,\n\t}\n}\n\nfunc (p *Proxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {\n\tdefer func() {\n\t\tif err := recover(); err != nil {\n\t\t\tLogger.With(slogger.Field{Key: \"error\", Value: err}).Errorf(\"Proxy: proxy causes panic\")\n\t\t\tvar errMsg string\n\t\t\tif e, ok := err.(error); ok {\n\t\t\t\terrMsg = e.Error()\n\t\t\t} else {\n\t\t\t\terrMsg = fmt.Sprintf(\"%v\", err)\n\t\t\t}\n\t\t\thttp.Error(w, errMsg, http.StatusBadGateway)\n\t\t}\n\t}()\n\n\thost, err := p.getSandboxHostDefinition(r)\n\tif err != nil {\n\t\thttp.Error(w, fmt.Sprintf(\"OpenSandbox Ingress: %v\", err), http.StatusBadRequest)\n\t\treturn\n\t}\n\n\ttargetHost, err, code := p.resolveRealHost(host)\n\tif err != nil {\n\t\thttp.Error(w, fmt.Sprintf(\"OpenSandbox Ingress: %v\", err), code)\n\t\treturn\n\t}\n\n\tif p.renewIntentPublisher != nil {\n\t\tp.renewIntentPublisher.PublishIntent(host.ingressKey, host.port, host.requestURI)\n\t}\n\n\t// modify if requestURI is not empty\n\tif host.requestURI != \"\" {\n\t\tr.URL.Path = host.requestURI\n\t}\n\n\tr.Host = targetHost\n\tr.URL.Host = targetHost\n\tr.Header.Del(SandboxIngress)\n\n\tLogger.With(\n\t\tslogger.Field{Key: \"target\", Value: targetHost},\n\t\tslogger.Field{Key: \"client\", Value: p.getClientIP(r)},\n\t\tslogger.Field{Key: \"uri\", Value: r.RequestURI},\n\t\tslogger.Field{Key: \"method\", Value: r.Method},\n\t).Infof(\"ingress requested\")\n\tp.serve(w, r)\n}\n\nfunc (p *Proxy) serve(w http.ResponseWriter, r *http.Request) {\n\tif p.isWebSocketRequest(r) {\n\t\tif r.URL == nil {\n\t\t\thttp.Error(w, \"invalid request URL\", http.StatusBadRequest)\n\t\t\treturn\n\t\t}\n\n\t\tif r.URL.Scheme == \"\" {\n\t\t\tif r.TLS != nil {\n\t\t\t\tr.URL.Scheme = \"wss\"\n\t\t\t} else {\n\t\t\t\tr.URL.Scheme = \"ws\"\n\t\t\t}\n\t\t}\n\t\tNewWebSocketProxy(r.URL).ServeHTTP(w, r)\n\t} else {\n\t\tif r.URL.Scheme == \"\" {\n\t\t\tif r.TLS != nil {\n\t\t\t\tr.URL.Scheme = \"https\"\n\t\t\t} else {\n\t\t\t\tr.URL.Scheme = \"http\"\n\t\t\t}\n\t\t}\n\t\tNewHTTPProxy().ServeHTTP(w, r)\n\t}\n}\n\nfunc (p *Proxy) isWebSocketRequest(r *http.Request) bool {\n\tif r.Method != http.MethodGet {\n\t\treturn false\n\t}\n\tif r.Header.Get(\"Upgrade\") != \"websocket\" {\n\t\treturn false\n\t}\n\tif r.Header.Get(\"Connection\") != \"Upgrade\" {\n\t\treturn false\n\t}\n\treturn true\n}\n\nfunc (p *Proxy) resolveRealHost(host *sandboxHost) (string, error, int) {\n\t// Get endpoint IP from sandbox provider\n\tendpointIP, err := p.sandboxProvider.GetEndpoint(host.ingressKey)\n\tif err != nil {\n\t\t// Map sandbox errors to HTTP status codes\n\t\tswitch {\n\t\tcase errors.Is(err, sandbox.ErrSandboxNotFound):\n\t\t\treturn \"\", err, http.StatusNotFound\n\t\tcase errors.Is(err, sandbox.ErrSandboxNotReady):\n\t\t\treturn \"\", err, http.StatusServiceUnavailable\n\t\tdefault:\n\t\t\treturn \"\", err, http.StatusBadGateway\n\t\t}\n\t}\n\n\t// Construct target host with port\n\ttargetHost := fmt.Sprintf(\"%s:%d\", endpointIP, host.port)\n\treturn targetHost, nil, 0\n}\n\nfunc (p *Proxy) getClientIP(r *http.Request) string {\n\tclientIP, _, _ := net.SplitHostPort(r.RemoteAddr)\n\tif len(r.Header.Get(XForwardedFor)) != 0 {\n\t\txff := r.Header.Get(XForwardedFor)\n\t\ts := strings.Index(xff, \", \")\n\t\tif s == -1 {\n\t\t\ts = len(r.Header.Get(XForwardedFor))\n\t\t}\n\t\tclientIP = xff[:s]\n\t} else if len(r.Header.Get(XRealIP)) != 0 {\n\t\tclientIP = r.Header.Get(XRealIP)\n\t}\n\n\treturn clientIP\n}\n" }, { "path": "components/ingress/pkg/proxy/proxy_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"net\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"testing\"\n\n\t\"github.com/stretchr/testify/assert\"\n)\n\n// Test_WatchPods is removed as we now use BatchSandbox Provider instead of direct Pod watching\n\nfunc TestIsWebSocketRequest(t *testing.T) {\n\tproxy := &Proxy{}\n\n\t// Valid websocket request\n\treq := httptest.NewRequest(http.MethodGet, \"/ws\", nil)\n\treq.Header.Set(\"Upgrade\", \"websocket\")\n\treq.Header.Set(\"Connection\", \"Upgrade\")\n\tassert.True(t, proxy.isWebSocketRequest(req))\n\n\t// Missing upgrade headers\n\treq = httptest.NewRequest(http.MethodGet, \"/ws\", nil)\n\tassert.False(t, proxy.isWebSocketRequest(req))\n\n\t// Wrong method\n\treq = httptest.NewRequest(http.MethodPost, \"/ws\", nil)\n\treq.Header.Set(\"Upgrade\", \"websocket\")\n\treq.Header.Set(\"Connection\", \"Upgrade\")\n\tassert.False(t, proxy.isWebSocketRequest(req))\n}\n\nfunc TestParseSandboxHost(t *testing.T) {\n\tproxy := &Proxy{}\n\n\thost, err := proxy.parseSandboxHost(\"sandbox-1234.example.com\")\n\tassert.NoError(t, err)\n\tassert.Equal(t, \"sandbox\", host.ingressKey)\n\tassert.Equal(t, 1234, host.port)\n\n\thost, err = proxy.parseSandboxHost(\"https://alpha-beta-8080.sandbox.test\")\n\tassert.NoError(t, err)\n\tassert.Equal(t, \"alpha-beta\", host.ingressKey)\n\tassert.Equal(t, 8080, host.port)\n\n\t_, err = proxy.parseSandboxHost(\"invalidhost\")\n\tassert.Error(t, err)\n\n\t_, err = proxy.parseSandboxHost(\"-1234.example.com\")\n\tassert.Error(t, err)\n}\n\nfunc TestGetClientIP(t *testing.T) {\n\tproxy := &Proxy{}\n\n\treq := httptest.NewRequest(http.MethodGet, \"/\", nil)\n\treq.RemoteAddr = \"192.0.2.1:12345\"\n\tassert.Equal(t, \"192.0.2.1\", proxy.getClientIP(req))\n\n\treq = httptest.NewRequest(http.MethodGet, \"/\", nil)\n\treq.RemoteAddr = \"192.0.2.1:12345\"\n\treq.Header.Set(XRealIP, \"203.0.113.5\")\n\tassert.Equal(t, \"203.0.113.5\", proxy.getClientIP(req))\n\n\treq = httptest.NewRequest(http.MethodGet, \"/\", nil)\n\treq.RemoteAddr = \"192.0.2.1:12345\"\n\treq.Header.Set(XForwardedFor, \"10.0.0.1, 198.51.100.2\")\n\tassert.Equal(t, \"10.0.0.1\", proxy.getClientIP(req))\n}\n\nfunc findAvailablePort() (int, error) {\n\tlistener, err := net.Listen(\"tcp\", \"127.0.0.1:0\")\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tdefer listener.Close()\n\n\tport := listener.Addr().(*net.TCPAddr).Port\n\treturn port, nil\n}\n" }, { "path": "components/ingress/pkg/proxy/websocket.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net\"\n\t\"net/http\"\n\t\"net/url\"\n\t\"strings\"\n\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n\t\"github.com/gorilla/websocket\"\n)\n\nvar (\n\t// defaultWebSocketDialer is a dialer with all fields set to the default zero values.\n\tdefaultWebSocketDialer = websocket.DefaultDialer\n\n\t// defaultUpgrader specifies the parameters for upgrading an HTTP\n\t// connection to a WebSocket connection.\n\tdefaultUpgrader = &websocket.Upgrader{\n\t\tReadBufferSize: 1024,\n\t\tWriteBufferSize: 1024,\n\t}\n)\n\n// WebSocketProxy is an HTTP Handler that takes an incoming WebSocket\n// connection and proxies it to another server.\ntype WebSocketProxy struct {\n\t// director, if non-nil, is a function that may copy additional request\n\t// headers from the incoming WebSocket connection into the output headers\n\t// which will be forwarded to another server.\n\tdirector func(incoming *http.Request, out http.Header)\n\n\t// backend returns the backend URL which the proxy uses to reverse proxy\n\t// the incoming WebSocket connection. Request is the initial incoming and\n\t// unmodified request.\n\tbackend func(*http.Request) *url.URL\n\n\t// dialer contains options for connecting to the backend WebSocket server.\n\t// If nil, DefaultDialer is used.\n\tdialer *websocket.Dialer\n\n\t// upgrader specifies the parameters for upgrading a incoming HTTP\n\t// connection to a WebSocket connection. If nil, DefaultUpgrader is used.\n\tupgrader *websocket.Upgrader\n}\n\n// ProxyHandler returns a new http.Handler interface that reverse proxies the\n// request to the given target.\nfunc ProxyHandler(target *url.URL) http.Handler { return NewWebSocketProxy(target) }\n\n// NewWebSocketProxy returns a new Websocket reverse proxy that rewrites the\n// URL's to the scheme, host and base path provider in target.\nfunc NewWebSocketProxy(target *url.URL) *WebSocketProxy {\n\tbackend := func(r *http.Request) *url.URL {\n\t\t// Shallow copy\n\t\tu := *target\n\t\tu.Fragment = r.URL.Fragment\n\t\tu.Path = r.URL.Path\n\t\tu.RawQuery = r.URL.RawQuery\n\t\treturn &u\n\t}\n\treturn &WebSocketProxy{backend: backend}\n}\n\n//nolint:gocognit\nfunc (w *WebSocketProxy) ServeHTTP(rw http.ResponseWriter, r *http.Request) {\n\tif w.backend == nil {\n\t\thttp.Error(rw, \"WebSocketProxy: backend is not defined\", http.StatusInternalServerError)\n\t\treturn\n\t}\n\n\tbackendURL := w.backend(r)\n\tif backendURL == nil {\n\t\thttp.Error(rw, \"WebSocketProxy: backend URL is nil\", http.StatusInternalServerError)\n\t\treturn\n\t}\n\n\tdialer := w.dialer\n\tif w.dialer == nil {\n\t\tdialer = defaultWebSocketDialer\n\t}\n\n\t// Pass headers from the incoming request to the dialer to forward them to\n\t// the final destinations.\n\trequestHeader := http.Header{}\n\tif origin := r.Header.Get(Origin); origin != \"\" {\n\t\trequestHeader.Add(Origin, origin)\n\t}\n\tfor _, prot := range r.Header[SecWebSocketProtocol] {\n\t\trequestHeader.Add(SecWebSocketProtocol, prot)\n\t}\n\tfor _, cokiee := range r.Header[Cookie] {\n\t\trequestHeader.Add(Cookie, cokiee)\n\t}\n\tif r.Host != \"\" {\n\t\trequestHeader.Set(Host, r.Host)\n\t}\n\n\t// Pass X-Forwarded-For headers too, code below is a part of\n\t// httputil.ReverseProxy. See http://en.wikipedia.org/wiki/X-Forwarded-For\n\t// for more information\n\tif clientIP, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {\n\t\t// If we aren't the first proxy retain prior\n\t\t// X-Forwarded-For information as a comma+space\n\t\t// separated list and fold multiple headers into one.\n\t\tif prior, ok := r.Header[XForwardedFor]; ok {\n\t\t\tclientIP = strings.Join(prior, \", \") + \", \" + clientIP\n\t\t}\n\t\trequestHeader.Set(XForwardedFor, clientIP)\n\t}\n\n\t// Set the originating protocol of the incoming HTTP request. The SSL might\n\t// be terminated on our site and because we doing proxy adding this would\n\t// be helpful for applications on the backend.\n\trequestHeader.Set(XForwardedProto, \"http\")\n\tif r.TLS != nil {\n\t\trequestHeader.Set(XForwardedProto, \"https\")\n\t}\n\n\t// Enable the director to copy any additional headers it desires for\n\t// forwarding to the remote server.\n\tif w.director != nil {\n\t\tw.director(r, requestHeader)\n\t}\n\n\t// Connect to the backend URL, also pass the headers we get from the requst\n\t// together with the Forwarded headers we prepared above.\n\tconnBackend, resp, err := dialer.Dial(backendURL.String(), requestHeader)\n\tif err != nil {\n\t\tLogger.With(slogger.Field{Key: \"error\", Value: err}).Errorf(\"WebSocketProxy: couldn't dial to remote backend\")\n\t\tif resp != nil {\n\t\t\t// If the WebSocket handshake fails, ErrBadHandshake is returned\n\t\t\t// along with a non-nil *http.Response so that callers can handle\n\t\t\t// redirects, authentication, etcetera.\n\t\t\tif err := copyResponse(rw, resp); err != nil {\n\t\t\t\tLogger.With(slogger.Field{Key: \"error\", Value: err}).Errorf(\"WebSocketProxy: couldn't write response after failed remote backend handshake\")\n\t\t\t}\n\t\t} else {\n\t\t\thttp.Error(rw, http.StatusText(http.StatusServiceUnavailable), http.StatusServiceUnavailable)\n\t\t}\n\t\treturn\n\t}\n\tdefer connBackend.Close()\n\n\tupgrader := w.upgrader\n\tif w.upgrader == nil {\n\t\tupgrader = defaultUpgrader\n\t}\n\n\t// Only pass those headers to the upgrader.\n\tupgradeHeader := http.Header{}\n\tif hdr := resp.Header.Get(SecWebSocketProtocol); hdr != \"\" {\n\t\tupgradeHeader.Set(SecWebSocketProtocol, hdr)\n\t}\n\tif hdr := resp.Header.Get(SetCookie); hdr != \"\" {\n\t\tupgradeHeader.Set(SetCookie, hdr)\n\t}\n\n\t// Now upgrade the existing incoming request to a WebSocket connection.\n\t// Also pass the header that we gathered from the Dial handshake.\n\tconnPub, err := upgrader.Upgrade(rw, r, upgradeHeader)\n\tif err != nil {\n\t\tLogger.With(slogger.Field{Key: \"error\", Value: err}).Errorf(\"WebSocketProxy: couldn't upgrade websocket connection\")\n\t\treturn\n\t}\n\tdefer connPub.Close()\n\n\terrClient := make(chan error, 1)\n\terrBackend := make(chan error, 1)\n\treplicateWebsocketConn := func(dst, src *websocket.Conn, errc chan error) {\n\t\tfor {\n\t\t\tmsgType, msg, err := src.ReadMessage()\n\t\t\tif err != nil {\n\t\t\t\tm := websocket.FormatCloseMessage(websocket.CloseNormalClosure, fmt.Sprintf(\"%v\", err))\n\t\t\t\tif e, ok := err.(*websocket.CloseError); ok { //nolint:errorlint\n\t\t\t\t\tif e.Code != websocket.CloseNoStatusReceived {\n\t\t\t\t\t\tm = websocket.FormatCloseMessage(e.Code, e.Text)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\terrc <- err\n\t\t\t\t_ = dst.WriteMessage(websocket.CloseMessage, m)\n\t\t\t\tbreak\n\t\t\t}\n\t\t\terr = dst.WriteMessage(msgType, msg)\n\t\t\tif err != nil {\n\t\t\t\terrc <- err\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t}\n\n\tgo replicateWebsocketConn(connPub, connBackend, errClient)\n\tgo replicateWebsocketConn(connBackend, connPub, errBackend)\n\n\tvar message string\n\tselect {\n\tcase err = <-errClient:\n\t\tmessage = \"WebSocketProxy: Error when copying from backend to client: %v\"\n\tcase err = <-errBackend:\n\t\tmessage = \"WebSocketProxy: Error when copying from client to backend: %v\"\n\n\t}\n\tif e, ok := err.(*websocket.CloseError); !ok || e.Code == websocket.CloseAbnormalClosure { //nolint:errorlint\n\t\tLogger.With(slogger.Field{Key: \"error\", Value: err}).Errorf(message, err)\n\t}\n}\n\nfunc copyResponse(rw http.ResponseWriter, resp *http.Response) error {\n\tcopyHeader(rw.Header(), resp.Header)\n\trw.WriteHeader(resp.StatusCode)\n\tdefer resp.Body.Close()\n\n\t_, err := io.Copy(rw, resp.Body)\n\treturn err\n}\n\nfunc copyHeader(dst, src http.Header) {\n\tfor k, vv := range src {\n\t\tfor _, v := range vv {\n\t\t\tdst.Add(k, v)\n\t\t}\n\t}\n}\n" }, { "path": "components/ingress/pkg/proxy/websocket_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage proxy\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"net/http\"\n\t\"strconv\"\n\t\"strings\"\n\t\"testing\"\n\t\"time\"\n\n\tslogger \"github.com/alibaba/opensandbox/internal/logger\"\n\t\"github.com/gorilla/websocket\"\n\t\"github.com/stretchr/testify/assert\"\n)\n\nfunc Test_WebSocketProxy(t *testing.T) {\n\tt.Run(\"with header mode\", func(t *testing.T) {\n\t\twebSocketProxyWithHeaderMode(t)\n\t})\n\tt.Run(\"with uri mode\", func(t *testing.T) {\n\t\twebSocketProxyWithURIMode(t)\n\t})\n}\n\nfunc webSocketProxyWithHeaderMode(t *testing.T) {\n\t// Create mock provider\n\tprovider := &mockProvider{\n\t\tendpoints: map[string]string{\n\t\t\t\"test-sandbox\": \"127.0.0.1\",\n\t\t},\n\t}\n\n\tctx := context.Background()\n\tLogger = slogger.MustNew(slogger.Config{Level: \"debug\"})\n\tproxy := NewProxy(ctx, provider, ModeHeader, nil)\n\n\tmux := http.NewServeMux()\n\tmux.Handle(\"/\", proxy)\n\tproxyPort, err := findAvailablePort()\n\tproxyURL := \"ws://127.0.0.1:\" + strconv.Itoa(proxyPort)\n\tassert.Nil(t, err)\n\n\tgo func() {\n\t\tassert.NoError(t, http.ListenAndServe(\":\"+strconv.Itoa(proxyPort), mux))\n\t}()\n\n\ttime.Sleep(2 * time.Second)\n\n\tbackendPort, err := findAvailablePort()\n\tassert.Nil(t, err)\n\n\t// backend echo server\n\tgo func() {\n\t\tmux2 := http.NewServeMux()\n\t\tmux2.HandleFunc(\"/ws\", func(w http.ResponseWriter, r *http.Request) {\n\t\t\tt.Logf(\"r.URL.Path: %s\", r.URL.Path)\n\t\t\tt.Logf(\"r.URL.RawPath: %s\", r.URL.RawPath)\n\t\t\tt.Logf(\"r.Host: %s\", r.Host)\n\t\t\t// Don't upgrade if original host header isn't preserved\n\t\t\tassert.True(t, strings.HasPrefix(r.Host, \"127.0.0.1\"))\n\n\t\t\tconn, err := defaultUpgrader.Upgrade(w, r, nil)\n\t\t\tif err != nil {\n\t\t\t\tlog.Println(err)\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tmessageType, p, err := conn.ReadMessage()\n\t\t\tif err != nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tif err = conn.WriteMessage(messageType, p); err != nil {\n\t\t\t\treturn\n\t\t\t}\n\t\t})\n\n\t\terr := http.ListenAndServe(\":\"+strconv.Itoa(backendPort), mux2)\n\t\tif err != nil {\n\t\t\tt.Error(\"ListenAndServe: \", err)\n\t\t\treturn\n\t\t}\n\t}()\n\n\ttime.Sleep(time.Millisecond * 100)\n\n\t// frontend server, dial now our proxy, which will reverse proxy our\n\t// message to the backend websocket server.\n\th := http.Header{}\n\th.Set(SandboxIngress, \"test-sandbox-\"+strconv.Itoa(backendPort))\n\tconn, _, err := websocket.DefaultDialer.Dial(proxyURL+\"/ws\", h)\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\n\t// write a message and send it to the backend server\n\tmsg := \"hello kite\"\n\terr = conn.WriteMessage(websocket.TextMessage, []byte(msg))\n\tif err != nil {\n\t\tt.Error(err)\n\t}\n\n\tmessageType, p, err := conn.ReadMessage()\n\tif err != nil {\n\t\tt.Error(err)\n\t}\n\n\tif messageType != websocket.TextMessage {\n\t\tt.Error(\"incoming message type is not Text\")\n\t}\n\n\tif msg != string(p) {\n\t\tt.Errorf(\"expecting: %s, got: %s\", msg, string(p))\n\t}\n}\n\nfunc webSocketProxyWithURIMode(t *testing.T) {\n\t// Create mock provider\n\tprovider := &mockProvider{\n\t\tendpoints: map[string]string{\n\t\t\t\"test-sandbox\": \"127.0.0.1\",\n\t\t},\n\t}\n\n\tctx := context.Background()\n\tLogger = slogger.MustNew(slogger.Config{Level: \"debug\"})\n\tproxy := NewProxy(ctx, provider, ModeURI, nil)\n\n\tmux := http.NewServeMux()\n\tmux.Handle(\"/\", proxy)\n\tproxyPort, err := findAvailablePort()\n\tproxyURL := \"ws://127.0.0.1:\" + strconv.Itoa(proxyPort)\n\tassert.Nil(t, err)\n\n\tgo func() {\n\t\tassert.NoError(t, http.ListenAndServe(\":\"+strconv.Itoa(proxyPort), mux))\n\t}()\n\n\ttime.Sleep(2 * time.Second)\n\n\tbackendPort, err := findAvailablePort()\n\tassert.Nil(t, err)\n\n\t// backend echo server\n\tgo func() {\n\t\tmux2 := http.NewServeMux()\n\t\tmux2.HandleFunc(\"/ws\", func(w http.ResponseWriter, r *http.Request) {\n\t\t\tt.Logf(\"r.URL.Path: %s\", r.URL.Path)\n\t\t\tt.Logf(\"r.URL.RawPath: %s\", r.URL.RawPath)\n\t\t\tt.Logf(\"r.Host: %s\", r.Host)\n\t\t\t// Don't upgrade if original host header isn't preserved\n\t\t\tassert.True(t, strings.HasPrefix(r.Host, \"127.0.0.1\"))\n\n\t\t\tconn, err := defaultUpgrader.Upgrade(w, r, nil)\n\t\t\tif err != nil {\n\t\t\t\tlog.Println(err)\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tmessageType, p, err := conn.ReadMessage()\n\t\t\tif err != nil {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tif err = conn.WriteMessage(messageType, p); err != nil {\n\t\t\t\treturn\n\t\t\t}\n\t\t})\n\n\t\terr := http.ListenAndServe(\":\"+strconv.Itoa(backendPort), mux2)\n\t\tif err != nil {\n\t\t\tt.Error(\"ListenAndServe: \", err)\n\t\t\treturn\n\t\t}\n\t}()\n\n\ttime.Sleep(time.Millisecond * 100)\n\n\t// frontend server, dial now our proxy, which will reverse proxy our\n\t// message to the backend websocket server.\n\th := http.Header{}\n\th.Set(SandboxIngress, \"test-sandbox-\"+strconv.Itoa(backendPort))\n\tconn, _, err := websocket.DefaultDialer.Dial(proxyURL+fmt.Sprintf(\"/test-sandbox/%v\", backendPort)+\"/ws\", h)\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\n\t// write a message and send it to the backend server\n\tmsg := \"hello kite\"\n\terr = conn.WriteMessage(websocket.TextMessage, []byte(msg))\n\tif err != nil {\n\t\tt.Error(err)\n\t}\n\n\tmessageType, p, err := conn.ReadMessage()\n\tif err != nil {\n\t\tt.Error(err)\n\t}\n\n\tif messageType != websocket.TextMessage {\n\t\tt.Error(\"incoming message type is not Text\")\n\t}\n\n\tif msg != string(p) {\n\t\tt.Errorf(\"expecting: %s, got: %s\", msg, string(p))\n\t}\n}\n" }, { "path": "components/ingress/pkg/renewintent/intent.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage renewintent\n\nimport \"time\"\n\ntype Intent struct {\n\tSandboxID string `json:\"sandbox_id\"`\n\tObservedAt string `json:\"observed_at\"`\n\tPort int `json:\"port,omitempty\"`\n\tRequestURI string `json:\"request_uri,omitempty\"`\n}\n\nfunc NewIntent(sandboxID string, port int, requestURI string) Intent {\n\treturn Intent{\n\t\tSandboxID: sandboxID,\n\t\tObservedAt: time.Now().UTC().Format(time.RFC3339Nano),\n\t\tPort: port,\n\t\tRequestURI: requestURI,\n\t}\n}\n" }, { "path": "components/ingress/pkg/renewintent/intent_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage renewintent\n\nimport (\n\t\"encoding/json\"\n\t\"testing\"\n\n\t\"github.com/stretchr/testify/assert\"\n)\n\nfunc TestNewIntent(t *testing.T) {\n\tintent := NewIntent(\"sb-123\", 8080, \"/api/foo\")\n\tassert.Equal(t, \"sb-123\", intent.SandboxID)\n\tassert.Equal(t, 8080, intent.Port)\n\tassert.Equal(t, \"/api/foo\", intent.RequestURI)\n\tassert.NotEmpty(t, intent.ObservedAt)\n}\n\nfunc TestIntent_JSONRoundTrip(t *testing.T) {\n\tintent := NewIntent(\"my-sandbox\", 80, \"/\")\n\tdata, err := json.Marshal(intent)\n\tassert.NoError(t, err)\n\tvar decoded Intent\n\terr = json.Unmarshal(data, &decoded)\n\tassert.NoError(t, err)\n\tassert.Equal(t, intent.SandboxID, decoded.SandboxID)\n\tassert.Equal(t, intent.Port, decoded.Port)\n\tassert.Equal(t, intent.RequestURI, decoded.RequestURI)\n}\n\nfunc TestIntent_JSONHasRequiredFields(t *testing.T) {\n\tintent := NewIntent(\"id\", 0, \"\")\n\tdata, err := json.Marshal(intent)\n\tassert.NoError(t, err)\n\tvar m map[string]interface{}\n\terr = json.Unmarshal(data, &m)\n\tassert.NoError(t, err)\n\tfor _, key := range []string{\"sandbox_id\", \"observed_at\"} {\n\t\t_, ok := m[key]\n\t\tassert.True(t, ok, \"missing required JSON field %q\", key)\n\t}\n}\n" }, { "path": "components/ingress/pkg/renewintent/publisher.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage renewintent\n\ntype Publisher interface {\n\tPublishIntent(sandboxID string, port int, requestURI string)\n}\n" }, { "path": "components/ingress/pkg/renewintent/redis.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage renewintent\n\nimport (\n\t\"context\"\n\t\"encoding/json\"\n\t\"errors\"\n\t\"sync\"\n\t\"sync/atomic\"\n\t\"time\"\n\n\t\"github.com/alibaba/opensandbox/internal/logger\"\n\t\"github.com/redis/go-redis/v9\"\n\t\"k8s.io/apimachinery/pkg/util/wait\"\n)\n\nconst (\n\tredisOpTimeout = 5 * time.Second\n\tpublishWorkers = 4\n\tpublishChanCap = 8192\n)\n\ntype RedisPublisherConfig struct {\n\tQueueKey string\n\tQueueMaxLen int\n\tMinInterval time.Duration\n\tLogger logger.Logger\n}\n\ntype intentReq struct {\n\tsandboxID string\n\tport int\n\trequestURI string\n}\n\ntype RedisPublisher struct {\n\tclient *redis.Client\n\tcfg RedisPublisherConfig\n\tlastSent sync.Map\n\tch chan intentReq\n\tstopped atomic.Bool\n}\n\nfunc NewRedisPublisher(ctx context.Context, client *redis.Client, cfg RedisPublisherConfig) *RedisPublisher {\n\tp := &RedisPublisher{client: client, cfg: cfg, ch: make(chan intentReq, publishChanCap)}\n\tfor i := 0; i < publishWorkers; i++ {\n\t\tgo func() {\n\t\t\tfor {\n\t\t\t\tselect {\n\t\t\t\tcase req := <-p.ch:\n\t\t\t\t\tp.doPublish(req.sandboxID, req.port, req.requestURI)\n\t\t\t\tcase <-ctx.Done():\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t}\n\t\t}()\n\t}\n\n\tgo func() {\n\t\t<-ctx.Done()\n\t\tp.stopped.Store(true)\n\t}()\n\n\tif cfg.MinInterval > 0 {\n\t\tgo wait.UntilWithContext(ctx, p.runCleanupThrottle, cfg.MinInterval*2)\n\t}\n\treturn p\n}\n\nfunc (p *RedisPublisher) shouldSendIntent(sandboxID string) bool {\n\tif p.cfg.MinInterval <= 0 {\n\t\treturn true\n\t}\n\tnow := time.Now()\n\tif v, ok := p.lastSent.Load(sandboxID); ok {\n\t\tif now.Sub(v.(time.Time)) < p.cfg.MinInterval {\n\t\t\treturn false\n\t\t}\n\t}\n\tp.lastSent.Store(sandboxID, now)\n\treturn true\n}\n\nfunc (p *RedisPublisher) PublishIntent(sandboxID string, port int, requestURI string) {\n\tif p.stopped.Load() {\n\t\treturn\n\t}\n\tselect {\n\tcase p.ch <- intentReq{sandboxID: sandboxID, port: port, requestURI: requestURI}:\n\tdefault:\n\t}\n}\n\nfunc (p *RedisPublisher) doPublish(sandboxID string, port int, requestURI string) {\n\tif !p.shouldSendIntent(sandboxID) {\n\t\treturn\n\t}\n\n\tintent := NewIntent(sandboxID, port, requestURI)\n\tpayload, err := json.Marshal(intent)\n\tif err != nil {\n\t\tp.cfg.Logger.With(logger.Field{Key: \"sandbox_id\", Value: sandboxID}).Errorf(\"renewintent: marshal intent: %v\", err)\n\t\treturn\n\t}\n\n\tctx, cancel := context.WithTimeout(context.Background(), redisOpTimeout)\n\tdefer cancel()\n\tpipe := p.client.Pipeline()\n\tpipe.LPush(ctx, p.cfg.QueueKey, string(payload))\n\tif p.cfg.QueueMaxLen > 0 {\n\t\tpipe.LTrim(ctx, p.cfg.QueueKey, 0, int64(p.cfg.QueueMaxLen-1))\n\t}\n\t_, err = pipe.Exec(ctx)\n\tif err != nil {\n\t\tp.cfg.Logger.With(\n\t\t\tlogger.Field{Key: \"sandbox_id\", Value: sandboxID},\n\t\t\tlogger.Field{Key: \"queue_key\", Value: p.cfg.QueueKey},\n\t\t\tlogger.Field{Key: \"error\", Value: err},\n\t\t).Errorf(\"renewintent: redis publish failed\")\n\t\treturn\n\t}\n\tp.cfg.Logger.With(\n\t\tlogger.Field{Key: \"sandbox_id\", Value: sandboxID},\n\t\tlogger.Field{Key: \"queue_key\", Value: p.cfg.QueueKey},\n\t).Debugf(\"renewintent: published\")\n}\n\nfunc RedisClientFromDSN(dsn string) (*redis.Client, error) {\n\topts, err := redis.ParseURL(dsn)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif opts == nil {\n\t\treturn nil, errors.New(\"renewintent: redis DSN produced nil options\")\n\t}\n\treturn redis.NewClient(opts), nil\n}\n\nfunc (p *RedisPublisher) runCleanupThrottle(_ context.Context) {\n\tcutoff := time.Now().Add(-p.cfg.MinInterval * 2)\n\tp.lastSent.Range(func(key, value any) bool {\n\t\tif value.(time.Time).Before(cutoff) {\n\t\t\tp.lastSent.Delete(key)\n\t\t}\n\t\treturn true\n\t})\n}\n" }, { "path": "components/ingress/pkg/renewintent/redis_bench_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage renewintent\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"testing\"\n\n\t\"github.com/alibaba/opensandbox/internal/logger\"\n\t\"github.com/alicebob/miniredis/v2\"\n\t\"github.com/redis/go-redis/v9\"\n)\n\ntype nopLogger struct{}\n\nfunc (nopLogger) Debugf(string, ...any) {}\nfunc (nopLogger) Infof(string, ...any) {}\nfunc (nopLogger) Warnf(string, ...any) {}\nfunc (nopLogger) Errorf(string, ...any) {}\nfunc (n nopLogger) With(...logger.Field) logger.Logger { return n }\nfunc (n nopLogger) Named(string) logger.Logger { return n }\nfunc (nopLogger) Sync() error { return nil }\n\n// Benchmarks use miniredis (in-memory Redis) so timing excludes real network I/O.\n\nfunc BenchmarkRedisPublisher_PublishIntent(b *testing.B) {\n\tmr, err := miniredis.Run()\n\tif err != nil {\n\t\tb.Fatal(err)\n\t}\n\tdefer mr.Close()\n\n\tclient := redis.NewClient(&redis.Options{Addr: mr.Addr()})\n\tdefer client.Close()\n\n\tctx, cancel := context.WithCancel(context.Background())\n\tdefer cancel()\n\n\tcfg := RedisPublisherConfig{\n\t\tQueueKey: \"opensandbox:renew:intent\",\n\t\tQueueMaxLen: 0,\n\t\tMinInterval: 0,\n\t\tLogger: nopLogger{},\n\t}\n\tp := NewRedisPublisher(ctx, client, cfg)\n\n\tsandboxID := \"bench-sandbox\"\n\tport := 8080\n\trequestURI := \"/api/health\"\n\n\tb.ResetTimer()\n\tfor i := 0; i < b.N; i++ {\n\t\tp.PublishIntent(sandboxID, port, requestURI)\n\t}\n}\n\nfunc BenchmarkRedisPublisher_PublishIntent_Throttled(b *testing.B) {\n\tmr, err := miniredis.Run()\n\tif err != nil {\n\t\tb.Fatal(err)\n\t}\n\tdefer mr.Close()\n\n\tclient := redis.NewClient(&redis.Options{Addr: mr.Addr()})\n\tdefer client.Close()\n\n\tctx, cancel := context.WithCancel(context.Background())\n\tdefer cancel()\n\tcfg := RedisPublisherConfig{\n\t\tQueueKey: \"opensandbox:renew:intent\",\n\t\tQueueMaxLen: 0,\n\t\tMinInterval: 1 << 30, // large so throttle skips most\n\t\tLogger: nopLogger{},\n\t}\n\tp := NewRedisPublisher(ctx, client, cfg)\n\n\tsandboxID := \"bench-sandbox\"\n\tport := 8080\n\trequestURI := \"/api/health\"\n\n\tb.ResetTimer()\n\tfor i := 0; i < b.N; i++ {\n\t\tp.PublishIntent(sandboxID, port, requestURI)\n\t}\n}\n\nfunc BenchmarkRedisPublisher_PublishIntent_ManySandboxes(b *testing.B) {\n\tmr, err := miniredis.Run()\n\tif err != nil {\n\t\tb.Fatal(err)\n\t}\n\tdefer mr.Close()\n\n\tclient := redis.NewClient(&redis.Options{Addr: mr.Addr()})\n\tdefer client.Close()\n\n\tctx, cancel := context.WithCancel(context.Background())\n\tdefer cancel()\n\tcfg := RedisPublisherConfig{\n\t\tQueueKey: \"opensandbox:renew:intent\",\n\t\tQueueMaxLen: 0,\n\t\tMinInterval: 0,\n\t\tLogger: nopLogger{},\n\t}\n\tp := NewRedisPublisher(ctx, client, cfg)\n\n\tport := 8080\n\trequestURI := \"/api/health\"\n\n\tb.ResetTimer()\n\tfor i := 0; i < b.N; i++ {\n\t\tsandboxID := fmt.Sprintf(\"sandbox-%d\", i%1000)\n\t\tp.PublishIntent(sandboxID, port, requestURI)\n\t}\n}\n" }, { "path": "components/ingress/pkg/sandbox/agent_sandbox_provider.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage sandbox\n\nimport (\n\t\"context\"\n\t\"crypto/sha256\"\n\t\"encoding/hex\"\n\t\"errors\"\n\t\"fmt\"\n\t\"regexp\"\n\t\"strings\"\n\t\"time\"\n\n\tmetav1 \"k8s.io/apimachinery/pkg/apis/meta/v1\"\n\t\"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured\"\n\t\"k8s.io/apimachinery/pkg/runtime/schema\"\n\t\"k8s.io/apimachinery/pkg/util/validation\"\n\t\"k8s.io/client-go/dynamic\"\n\t\"k8s.io/client-go/dynamic/dynamicinformer\"\n\t\"k8s.io/client-go/rest\"\n\t\"k8s.io/client-go/tools/cache\"\n)\n\nconst (\n\tagentSandboxGroup = \"agents.x-k8s.io\"\n\tagentSandboxVersion = \"v1alpha1\"\n\tagentSandboxResource = \"sandboxes\"\n\n\tagentSandboxConditionReady = \"Ready\"\n\tagentSandboxNamePrefix = \"sandbox\"\n)\n\nvar (\n\tdns1035InvalidChars = regexp.MustCompile(`[^a-z0-9-]+`)\n\tdns1035DuplicateHyphens = regexp.MustCompile(`-+`)\n)\n\n// AgentSandboxProvider implements Provider for agents.x-k8s.io Sandbox CR.\n// It uses a dynamic informer to watch resources in the target namespace.\ntype AgentSandboxProvider struct {\n\tinformerFactory dynamicinformer.DynamicSharedInformerFactory\n\tinformer cache.SharedIndexInformer\n\tnamespace string\n\tgvr schema.GroupVersionResource\n}\n\n// NewAgentSandboxProvider creates a Provider backed by dynamic informer.\nfunc NewAgentSandboxProvider(config *rest.Config, namespace string, resyncPeriod time.Duration) *AgentSandboxProvider {\n\tdyn, err := dynamic.NewForConfig(config)\n\tif err != nil {\n\t\tpanic(fmt.Sprintf(\"failed to create dynamic client: %v\", err))\n\t}\n\n\treturn newAgentSandboxProviderWithClient(dyn, namespace, resyncPeriod)\n}\n\n// newAgentSandboxProviderWithClient is a helper for tests to inject fake dynamic client.\nfunc newAgentSandboxProviderWithClient(dyn dynamic.Interface, namespace string, resyncPeriod time.Duration) *AgentSandboxProvider {\n\tgvr := schema.GroupVersionResource{\n\t\tGroup: agentSandboxGroup,\n\t\tVersion: agentSandboxVersion,\n\t\tResource: agentSandboxResource,\n\t}\n\n\tfactory := dynamicinformer.NewFilteredDynamicSharedInformerFactory(\n\t\tdyn,\n\t\tresyncPeriod,\n\t\tnamespace,\n\t\tnil, // no extra list options\n\t)\n\n\tinformer := factory.ForResource(gvr).Informer()\n\n\treturn &AgentSandboxProvider{\n\t\tinformerFactory: factory,\n\t\tinformer: informer,\n\t\tnamespace: namespace,\n\t\tgvr: gvr,\n\t}\n}\n\nfunc agentSandboxResourceName(sandboxId string) string {\n\treturn toDNS1035Label(sandboxId, agentSandboxNamePrefix)\n}\n\nfunc toDNS1035Label(value, prefix string) string {\n\tnormalized := strings.ToLower(strings.TrimSpace(value))\n\tnormalized = dns1035InvalidChars.ReplaceAllString(normalized, \"-\")\n\tnormalized = dns1035DuplicateHyphens.ReplaceAllString(normalized, \"-\")\n\tnormalized = strings.Trim(normalized, \"-\")\n\n\thash := sha256.Sum256([]byte(value))\n\tsuffix := hex.EncodeToString(hash[:])[:8]\n\n\tif normalized == \"\" {\n\t\tnormalized = prefix + \"-\" + suffix\n\t} else if !startsWithLetter(normalized) {\n\t\tnormalized = prefix + \"-\" + normalized\n\t}\n\n\tif len(normalized) > validation.DNS1035LabelMaxLength {\n\t\tmaxBase := validation.DNS1035LabelMaxLength - len(suffix) - 1\n\t\tbase := normalized\n\t\tif len(base) > maxBase {\n\t\t\tbase = base[:maxBase]\n\t\t}\n\t\tbase = strings.Trim(base, \"-\")\n\t\tif !startsWithLetter(base) {\n\t\t\tbase = prefix\n\t\t}\n\t\tnormalized = base + \"-\" + suffix\n\t}\n\n\treturn strings.Trim(normalized, \"-\")\n}\n\nfunc startsWithLetter(value string) bool {\n\tif value == \"\" {\n\t\treturn false\n\t}\n\tfirst := value[0]\n\treturn first >= 'a' && first <= 'z'\n}\n\nfunc legacyAgentSandboxName(sandboxId string) string {\n\tlegacyPrefix := agentSandboxNamePrefix + \"-\"\n\tif strings.HasPrefix(sandboxId, legacyPrefix) {\n\t\treturn sandboxId\n\t}\n\treturn legacyPrefix + sandboxId\n}\n\nfunc resourceNameCandidates(sandboxId string) []string {\n\tcandidates := []string{}\n\tprimary := agentSandboxResourceName(sandboxId)\n\tcandidates = append(candidates, primary)\n\tif sandboxId != primary {\n\t\tcandidates = append(candidates, sandboxId)\n\t}\n\tlegacy := legacyAgentSandboxName(sandboxId)\n\tif legacy != primary && legacy != sandboxId {\n\t\tcandidates = append(candidates, legacy)\n\t}\n\treturn candidates\n}\n\nfunc (a *AgentSandboxProvider) GetEndpoint(sandboxId string) (string, error) {\n\tcandidates := resourceNameCandidates(sandboxId)\n\tvar (\n\t\tobj any\n\t\texists bool\n\t\terr error\n\t)\n\tfor _, name := range candidates {\n\t\tkey := fmt.Sprintf(\"%s/%s\", a.namespace, name)\n\t\tobj, exists, err = a.informer.GetStore().GetByKey(key)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to get AgentSandbox %s: %w\", key, err)\n\t\t}\n\t\tif exists {\n\t\t\tbreak\n\t\t}\n\t}\n\tif !exists {\n\t\treturn \"\", fmt.Errorf(\"%w: %s/%s\", ErrSandboxNotFound, a.namespace, sandboxId)\n\t}\n\n\tu, ok := obj.(*unstructured.Unstructured)\n\tif !ok {\n\t\treturn \"\", fmt.Errorf(\"unexpected object type for sandbox %s: %T\", sandboxId, obj)\n\t}\n\n\tstatus, ok := u.Object[\"status\"].(map[string]any)\n\tif !ok {\n\t\treturn \"\", fmt.Errorf(\"%w: sandbox %s missing status\", ErrSandboxNotReady, sandboxId)\n\t}\n\n\t// Check ready condition first; must be Ready=True to proceed.\n\tif ready, reason, message := a.checkSandboxReadyCondition(status); !ready {\n\t\treturn \"\", fmt.Errorf(\"%w: sandbox %s not ready (%s: %s)\", ErrSandboxNotReady, sandboxId, reason, message)\n\t}\n\n\tserviceFQDN, _ := status[\"serviceFQDN\"].(string)\n\tif serviceFQDN == \"\" {\n\t\treturn \"\", fmt.Errorf(\"%w: sandbox %s has no serviceFQDN\", ErrSandboxNotReady, sandboxId)\n\t}\n\n\treturn serviceFQDN, nil\n}\n\n// Start starts the informer factory and waits for cache sync.\nfunc (a *AgentSandboxProvider) Start(ctx context.Context) error {\n\ta.informerFactory.Start(ctx.Done())\n\n\tif !cache.WaitForCacheSync(ctx.Done(), a.informer.HasSynced) {\n\t\treturn errors.New(\"failed to sync AgentSandbox informer cache\")\n\t}\n\n\treturn nil\n}\n\n// checkSandboxReadyCondition inspects status.conditions for Ready=True.\n// Returns (isReady, reason, message).\n//\n// https://github.com/kubernetes-sigs/agent-sandbox/blob/main/controllers/sandbox_controller.go#L195\nfunc (a *AgentSandboxProvider) checkSandboxReadyCondition(status map[string]any) (bool, string, string) {\n\tconds, ok := status[\"conditions\"].([]any)\n\tif !ok {\n\t\treturn false, \"NoConditions\", \"no sandbox conditions reported\"\n\t}\n\tfor _, c := range conds {\n\t\tm, ok := c.(map[string]any)\n\t\tif !ok {\n\t\t\tcontinue\n\t\t}\n\t\tif t, _ := m[\"type\"].(string); t != agentSandboxConditionReady {\n\t\t\tcontinue\n\t\t}\n\t\tif s, _ := m[\"status\"].(string); s == string(metav1.ConditionTrue) {\n\t\t\treturn true, agentSandboxConditionReady, \"\"\n\t\t}\n\t\treason, _ := m[\"reason\"].(string)\n\t\tmessage, _ := m[\"message\"].(string)\n\t\tif reason == \"\" {\n\t\t\treason = \"DependenciesNotReady\"\n\t\t}\n\t\tif message == \"\" {\n\t\t\tmessage = \"Ready condition is not True\"\n\t\t}\n\t\treturn false, reason, message\n\t}\n\n\treturn false, \"ReadyConditionMissing\", \"ready condition missing\"\n}\n\nvar _ Provider = (*AgentSandboxProvider)(nil)\n" }, { "path": "components/ingress/pkg/sandbox/agent_sandbox_provider_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage sandbox\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"strings\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/stretchr/testify/assert\"\n\t\"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured\"\n\t\"k8s.io/apimachinery/pkg/runtime\"\n\t\"k8s.io/apimachinery/pkg/runtime/schema\"\n\tdynamicfake \"k8s.io/client-go/dynamic/fake\"\n)\n\n// buildUnstructuredSandbox creates a minimal unstructured Sandbox object.\nfunc buildUnstructuredSandbox(name, namespace string) *unstructured.Unstructured {\n\treturn &unstructured.Unstructured{\n\t\tObject: map[string]any{\n\t\t\t\"apiVersion\": agentSandboxGroup + \"/\" + agentSandboxVersion,\n\t\t\t\"kind\": \"Sandbox\",\n\t\t\t\"metadata\": map[string]any{\n\t\t\t\t\"name\": name,\n\t\t\t\t\"namespace\": namespace,\n\t\t\t},\n\t\t\t\"spec\": map[string]any{\n\t\t\t\t\"podTemplate\": map[string]any{\n\t\t\t\t\t\"spec\": map[string]any{\n\t\t\t\t\t\t\"containers\": []any{},\n\t\t\t\t\t},\n\t\t\t\t\t\"metadata\": map[string]any{},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t}\n}\n\nfunc TestAgentSandboxProvider_Start_Success(t *testing.T) {\n\tnamespace := \"test-ns\"\n\n\tobj := buildUnstructuredSandbox(\"demo\", namespace)\n\tscheme := runtime.NewScheme()\n\tgvr := schema.GroupVersionResource{\n\t\tGroup: agentSandboxGroup,\n\t\tVersion: agentSandboxVersion,\n\t\tResource: agentSandboxResource,\n\t}\n\tfakeDyn := dynamicfake.NewSimpleDynamicClientWithCustomListKinds(\n\t\tscheme,\n\t\tmap[schema.GroupVersionResource]string{\n\t\t\tgvr: \"SandboxList\",\n\t\t},\n\t\tobj,\n\t)\n\n\tprovider := newAgentSandboxProviderWithClient(fakeDyn, namespace, 30*time.Second)\n\n\tctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)\n\tdefer cancel()\n\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err, \"Start should succeed with fake dynamic informer\")\n\n\t// Manually seed store (fake dynamic client doesn't backfill informer cache automatically)\n\terr = provider.informer.GetStore().Add(obj)\n\tassert.NoError(t, err)\n\n\tkey := obj.GetNamespace() + \"/\" + obj.GetName()\n\t_, exists, _ := provider.informer.GetStore().GetByKey(key)\n\tassert.True(t, exists, \"informer cache should accept added object after start\")\n}\n\nfunc TestAgentSandboxProvider_Start_ContextCancelled(t *testing.T) {\n\tnamespace := \"test-ns\"\n\n\tscheme := runtime.NewScheme()\n\tgvr := schema.GroupVersionResource{\n\t\tGroup: agentSandboxGroup,\n\t\tVersion: agentSandboxVersion,\n\t\tResource: agentSandboxResource,\n\t}\n\tfakeDyn := dynamicfake.NewSimpleDynamicClientWithCustomListKinds(\n\t\tscheme,\n\t\tmap[schema.GroupVersionResource]string{\n\t\t\tgvr: \"SandboxList\",\n\t\t},\n\t)\n\n\tprovider := newAgentSandboxProviderWithClient(fakeDyn, namespace, 30*time.Second)\n\n\tctx, cancel := context.WithCancel(context.Background())\n\tcancel() // cancel before start\n\n\terr := provider.Start(ctx)\n\tassert.Error(t, err, \"Start should fail when context already cancelled\")\n}\n\nfunc TestAgentSandboxProvider_GetEndpoint_ServiceFQDN(t *testing.T) {\n\tnamespace := \"test-ns\"\n\tobj := buildUnstructuredSandbox(\"demo\", namespace)\n\tobj.Object[\"status\"] = map[string]any{\n\t\t\"serviceFQDN\": \"sandbox.demo.svc.cluster.local\",\n\t\t\"conditions\": []any{\n\t\t\tmap[string]any{\n\t\t\t\t\"type\": \"Ready\",\n\t\t\t\t\"status\": \"True\",\n\t\t\t},\n\t\t},\n\t}\n\n\tscheme := runtime.NewScheme()\n\tgvr := schema.GroupVersionResource{\n\t\tGroup: agentSandboxGroup,\n\t\tVersion: agentSandboxVersion,\n\t\tResource: agentSandboxResource,\n\t}\n\tfakeDyn := dynamicfake.NewSimpleDynamicClientWithCustomListKinds(\n\t\tscheme,\n\t\tmap[schema.GroupVersionResource]string{\n\t\t\tgvr: \"SandboxList\",\n\t\t},\n\t)\n\n\tprovider := newAgentSandboxProviderWithClient(fakeDyn, namespace, 30*time.Second)\n\n\tctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)\n\tdefer cancel()\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err)\n\n\t// Seed store\n\terr = provider.informer.GetStore().Add(obj)\n\tassert.NoError(t, err)\n\n\tendpoint, err := provider.GetEndpoint(\"demo\")\n\tassert.NoError(t, err)\n\tassert.Equal(t, \"sandbox.demo.svc.cluster.local\", endpoint)\n}\n\nfunc TestAgentSandboxProvider_GetEndpoint_NotFound(t *testing.T) {\n\tnamespace := \"test-ns\"\n\n\tscheme := runtime.NewScheme()\n\tgvr := schema.GroupVersionResource{\n\t\tGroup: agentSandboxGroup,\n\t\tVersion: agentSandboxVersion,\n\t\tResource: agentSandboxResource,\n\t}\n\tfakeDyn := dynamicfake.NewSimpleDynamicClientWithCustomListKinds(\n\t\tscheme,\n\t\tmap[schema.GroupVersionResource]string{\n\t\t\tgvr: \"SandboxList\",\n\t\t},\n\t)\n\n\tprovider := newAgentSandboxProviderWithClient(fakeDyn, namespace, 30*time.Second)\n\n\tctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)\n\tdefer cancel()\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err)\n\n\t_, err = provider.GetEndpoint(\"missing\")\n\tassert.Error(t, err)\n\tassert.True(t, errors.Is(err, ErrSandboxNotFound))\n}\n\nfunc TestAgentSandboxProvider_GetEndpoint_NoServiceFQDN(t *testing.T) {\n\tnamespace := \"test-ns\"\n\tobj := buildUnstructuredSandbox(\"demo\", namespace)\n\tobj.Object[\"status\"] = map[string]any{}\n\n\tscheme := runtime.NewScheme()\n\tgvr := schema.GroupVersionResource{\n\t\tGroup: agentSandboxGroup,\n\t\tVersion: agentSandboxVersion,\n\t\tResource: agentSandboxResource,\n\t}\n\tfakeDyn := dynamicfake.NewSimpleDynamicClientWithCustomListKinds(\n\t\tscheme,\n\t\tmap[schema.GroupVersionResource]string{\n\t\t\tgvr: \"SandboxList\",\n\t\t},\n\t)\n\n\tprovider := newAgentSandboxProviderWithClient(fakeDyn, namespace, 30*time.Second)\n\n\tctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)\n\tdefer cancel()\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err)\n\n\t// Seed store\n\terr = provider.informer.GetStore().Add(obj)\n\tassert.NoError(t, err)\n\n\t_, err = provider.GetEndpoint(\"demo\")\n\tassert.Error(t, err)\n\tassert.True(t, errors.Is(err, ErrSandboxNotReady))\n}\n\nfunc TestAgentSandboxProvider_GetEndpoint_NotReadyCondition(t *testing.T) {\n\tnamespace := \"test-ns\"\n\tobj := buildUnstructuredSandbox(\"demo\", namespace)\n\tobj.Object[\"status\"] = map[string]any{\n\t\t\"serviceFQDN\": \"sandbox.demo.svc.cluster.local\",\n\t\t\"conditions\": []any{\n\t\t\tmap[string]any{\n\t\t\t\t\"type\": \"Ready\",\n\t\t\t\t\"status\": \"False\",\n\t\t\t\t\"reason\": \"DependenciesNotReady\",\n\t\t\t\t\"message\": \"Pod not ready\",\n\t\t\t},\n\t\t},\n\t}\n\n\tscheme := runtime.NewScheme()\n\tgvr := schema.GroupVersionResource{\n\t\tGroup: agentSandboxGroup,\n\t\tVersion: agentSandboxVersion,\n\t\tResource: agentSandboxResource,\n\t}\n\tfakeDyn := dynamicfake.NewSimpleDynamicClientWithCustomListKinds(\n\t\tscheme,\n\t\tmap[schema.GroupVersionResource]string{\n\t\t\tgvr: \"SandboxList\",\n\t\t},\n\t)\n\n\tprovider := newAgentSandboxProviderWithClient(fakeDyn, namespace, 30*time.Second)\n\n\tctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)\n\tdefer cancel()\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err)\n\n\t// Seed store\n\terr = provider.informer.GetStore().Add(obj)\n\tassert.NoError(t, err)\n\n\t_, err = provider.GetEndpoint(\"demo\")\n\tassert.Error(t, err)\n\tassert.True(t, errors.Is(err, ErrSandboxNotReady))\n}\n\nfunc TestToDNS1035Label_HashOnSymbolOnlyIDs(t *testing.T) {\n\tname1 := toDNS1035Label(\"!!!\", agentSandboxNamePrefix)\n\tname2 := toDNS1035Label(\"???\", agentSandboxNamePrefix)\n\n\tassert.NotEqual(t, name1, name2)\n\tassert.Regexp(t, `^sandbox-[0-9a-f]{8}$`, name1)\n\tassert.Regexp(t, `^sandbox-[0-9a-f]{8}$`, name2)\n}\n\nfunc TestToDNS1035Label_PrefixesDigitStart(t *testing.T) {\n\tname := toDNS1035Label(\"1234\", agentSandboxNamePrefix)\n\tassert.Equal(t, \"sandbox-1234\", name)\n}\n\nfunc TestToDNS1035Label_TruncatesWithHashSuffix(t *testing.T) {\n\tinput := \"A\" + strings.Repeat(\"b\", 100)\n\tname := toDNS1035Label(input, agentSandboxNamePrefix)\n\n\tassert.LessOrEqual(t, len(name), 63)\n\tassert.Regexp(t, `^[a-z][a-z0-9-]*$`, name)\n\tassert.Regexp(t, `[0-9a-f]{8}$`, name)\n}\n" }, { "path": "components/ingress/pkg/sandbox/batchsandbox_provider.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage sandbox\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"fmt\"\n\t\"time\"\n\n\tkerrors \"k8s.io/apimachinery/pkg/api/errors\"\n\t\"k8s.io/client-go/rest\"\n\t\"k8s.io/client-go/tools/cache\"\n\n\tclientset \"github.com/alibaba/OpenSandbox/sandbox-k8s/pkg/client/clientset/versioned\"\n\tinformers \"github.com/alibaba/OpenSandbox/sandbox-k8s/pkg/client/informers/externalversions\"\n\tlisters \"github.com/alibaba/OpenSandbox/sandbox-k8s/pkg/client/listers/sandbox/v1alpha1\"\n\t\"github.com/alibaba/OpenSandbox/sandbox-k8s/pkg/utils\"\n)\n\n// BatchSandboxProvider implements Provider interface for BatchSandbox resources\ntype BatchSandboxProvider struct {\n\tinformerFactory informers.SharedInformerFactory\n\tlister listers.BatchSandboxLister\n\tinformerSynced cache.InformerSynced\n\tnamespace string\n}\n\n// NewBatchSandboxProvider creates a new BatchSandboxProvider\nfunc NewBatchSandboxProvider(\n\tconfig *rest.Config,\n\tnamespace string,\n\tresyncPeriod time.Duration,\n) *BatchSandboxProvider {\n\tclientset, err := clientset.NewForConfig(config)\n\tif err != nil {\n\t\tpanic(fmt.Sprintf(\"failed to create sandbox clientset: %v\", err))\n\t}\n\n\tinformerFactory := informers.NewSharedInformerFactoryWithOptions(\n\t\tclientset,\n\t\tresyncPeriod,\n\t\tinformers.WithNamespace(namespace),\n\t)\n\n\tbatchSandboxInformer := informerFactory.Sandbox().V1alpha1().BatchSandboxes()\n\n\treturn &BatchSandboxProvider{\n\t\tinformerFactory: informerFactory,\n\t\tlister: batchSandboxInformer.Lister(),\n\t\tinformerSynced: batchSandboxInformer.Informer().HasSynced,\n\t\tnamespace: namespace,\n\t}\n}\n\n// Start starts the informer factory and waits for cache sync\nfunc (p *BatchSandboxProvider) Start(ctx context.Context) error {\n\tp.informerFactory.Start(ctx.Done())\n\n\t// Wait for cache sync\n\tif !cache.WaitForCacheSync(ctx.Done(), p.informerSynced) {\n\t\treturn errors.New(\"failed to sync BatchSandbox informer cache\")\n\t}\n\n\treturn nil\n}\n\n// GetEndpoint retrieves the endpoint IP for a BatchSandbox\nfunc (p *BatchSandboxProvider) GetEndpoint(sandboxId string) (string, error) {\n\t// Get BatchSandbox from cache using lister with provider's namespace\n\tbatchSandbox, err := p.lister.BatchSandboxes(p.namespace).Get(sandboxId)\n\tif err != nil {\n\t\tif kerrors.IsNotFound(err) {\n\t\t\treturn \"\", fmt.Errorf(\"%w: %s/%s\", ErrSandboxNotFound, p.namespace, sandboxId)\n\t\t}\n\t\treturn \"\", fmt.Errorf(\"failed to get BatchSandbox %s/%s: %w\", p.namespace, sandboxId, err)\n\t}\n\n\t// Check if BatchSandbox is ready\n\tif batchSandbox.Status.Ready < 1 {\n\t\treturn \"\", fmt.Errorf(\"%w: %s/%s (ready: %d/%d)\",\n\t\t\tErrSandboxNotReady, p.namespace, sandboxId, batchSandbox.Status.Ready, batchSandbox.Status.Replicas)\n\t}\n\n\t// Get endpoints from BatchSandbox using kubernetes utils\n\tendpoints, err := utils.GetEndpoints(batchSandbox)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"%w: %s/%s: %w\", ErrSandboxNotReady, p.namespace, sandboxId, err)\n\t}\n\n\t// Return the first available endpoint\n\treturn endpoints[0], nil\n}\n\nvar _ Provider = (*BatchSandboxProvider)(nil)\n" }, { "path": "components/ingress/pkg/sandbox/batchsandbox_provider_test.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage sandbox\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/stretchr/testify/assert\"\n\tmetav1 \"k8s.io/apimachinery/pkg/apis/meta/v1\"\n\n\tsandboxv1alpha1 \"github.com/alibaba/OpenSandbox/sandbox-k8s/apis/sandbox/v1alpha1\"\n\tfakeclientset \"github.com/alibaba/OpenSandbox/sandbox-k8s/pkg/client/clientset/versioned/fake\"\n\tinformers \"github.com/alibaba/OpenSandbox/sandbox-k8s/pkg/client/informers/externalversions\"\n\t\"github.com/alibaba/OpenSandbox/sandbox-k8s/pkg/utils\"\n)\n\n// Note: Integration tests with real informers are in e2e tests\n// Unit tests here focus on provider behavior\n\n// TestBatchSandboxProvider_WithFakeInformer tests the provider using fake clientset and informer\nfunc TestBatchSandboxProvider_WithFakeInformer(t *testing.T) {\n\tnamespace := \"test-namespace\"\n\n\t// Create a ready BatchSandbox with valid endpoints\n\treadyBatchSandbox := &sandboxv1alpha1.BatchSandbox{\n\t\tObjectMeta: metav1.ObjectMeta{\n\t\t\tName: \"ready-sandbox\",\n\t\t\tNamespace: namespace,\n\t\t\tAnnotations: map[string]string{\n\t\t\t\tutils.AnnotationEndpoints: `[\"10.0.0.1\", \"10.0.0.2\"]`,\n\t\t\t},\n\t\t},\n\t\tSpec: sandboxv1alpha1.BatchSandboxSpec{\n\t\t\tReplicas: ptr(int32(2)),\n\t\t},\n\t\tStatus: sandboxv1alpha1.BatchSandboxStatus{\n\t\t\tReplicas: 2,\n\t\t\tReady: 2,\n\t\t},\n\t}\n\n\t// Create a not ready BatchSandbox\n\tnotReadyBatchSandbox := &sandboxv1alpha1.BatchSandbox{\n\t\tObjectMeta: metav1.ObjectMeta{\n\t\t\tName: \"not-ready-sandbox\",\n\t\t\tNamespace: namespace,\n\t\t},\n\t\tSpec: sandboxv1alpha1.BatchSandboxSpec{\n\t\t\tReplicas: ptr(int32(1)),\n\t\t},\n\t\tStatus: sandboxv1alpha1.BatchSandboxStatus{\n\t\t\tReplicas: 1,\n\t\t\tReady: 0,\n\t\t},\n\t}\n\n\t// Create fake clientset with test objects\n\tfakeClient := fakeclientset.NewSimpleClientset(readyBatchSandbox, notReadyBatchSandbox)\n\n\t// Create informer factory\n\tinformerFactory := informers.NewSharedInformerFactoryWithOptions(\n\t\tfakeClient,\n\t\ttime.Second*30,\n\t\tinformers.WithNamespace(namespace),\n\t)\n\n\tbatchSandboxInformer := informerFactory.Sandbox().V1alpha1().BatchSandboxes()\n\n\t// Create provider\n\tprovider := &BatchSandboxProvider{\n\t\tinformerFactory: informerFactory,\n\t\tlister: batchSandboxInformer.Lister(),\n\t\tinformerSynced: batchSandboxInformer.Informer().HasSynced,\n\t\tnamespace: namespace,\n\t}\n\n\t// Start informer and wait for cache sync\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err, \"Provider should start successfully\")\n\n\t// Manually add objects to informer cache (fake clientset doesn't auto-populate informer)\n\terr = batchSandboxInformer.Informer().GetStore().Add(readyBatchSandbox)\n\tassert.NoError(t, err)\n\terr = batchSandboxInformer.Informer().GetStore().Add(notReadyBatchSandbox)\n\tassert.NoError(t, err)\n\n\t// Test 1: Get endpoint from ready sandbox\n\tt.Run(\"GetEndpoint from ready sandbox\", func(t *testing.T) {\n\t\tendpoint, err := provider.GetEndpoint(\"ready-sandbox\")\n\t\tassert.NoError(t, err)\n\t\tassert.Equal(t, \"10.0.0.1\", endpoint, \"Should return first endpoint IP\")\n\t})\n\n\t// Test 2: Get endpoint from not ready sandbox\n\tt.Run(\"GetEndpoint from not ready sandbox\", func(t *testing.T) {\n\t\t_, err := provider.GetEndpoint(\"not-ready-sandbox\")\n\t\tassert.Error(t, err)\n\t\tassert.True(t, errors.Is(err, ErrSandboxNotReady), \"Should return ErrSandboxNotReady\")\n\t\tassert.Contains(t, err.Error(), \"not ready\")\n\t})\n\n\t// Test 3: Get endpoint from non-existent sandbox\n\tt.Run(\"GetEndpoint from non-existent sandbox\", func(t *testing.T) {\n\t\t_, err := provider.GetEndpoint(\"non-existent\")\n\t\tassert.Error(t, err)\n\t\tassert.True(t, errors.Is(err, ErrSandboxNotFound), \"Should return ErrSandboxNotFound\")\n\t\tassert.Contains(t, err.Error(), \"not found\")\n\t})\n}\n\n// TestBatchSandboxProvider_MissingAnnotation tests sandbox without endpoints annotation\nfunc TestBatchSandboxProvider_MissingAnnotation(t *testing.T) {\n\tnamespace := \"test-namespace\"\n\n\t// Create BatchSandbox without endpoints annotation\n\tbatchSandbox := &sandboxv1alpha1.BatchSandbox{\n\t\tObjectMeta: metav1.ObjectMeta{\n\t\t\tName: \"no-annotation-sandbox\",\n\t\t\tNamespace: namespace,\n\t\t},\n\t\tSpec: sandboxv1alpha1.BatchSandboxSpec{\n\t\t\tReplicas: ptr(int32(1)),\n\t\t},\n\t\tStatus: sandboxv1alpha1.BatchSandboxStatus{\n\t\t\tReplicas: 1,\n\t\t\tReady: 1,\n\t\t},\n\t}\n\n\tfakeClient := fakeclientset.NewSimpleClientset(batchSandbox)\n\tinformerFactory := informers.NewSharedInformerFactoryWithOptions(\n\t\tfakeClient,\n\t\ttime.Second*30,\n\t\tinformers.WithNamespace(namespace),\n\t)\n\n\tbatchSandboxInformer := informerFactory.Sandbox().V1alpha1().BatchSandboxes()\n\n\tprovider := &BatchSandboxProvider{\n\t\tinformerFactory: informerFactory,\n\t\tlister: batchSandboxInformer.Lister(),\n\t\tinformerSynced: batchSandboxInformer.Informer().HasSynced,\n\t\tnamespace: namespace,\n\t}\n\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err)\n\n\t// Manually add object to informer cache\n\terr = batchSandboxInformer.Informer().GetStore().Add(batchSandbox)\n\tassert.NoError(t, err)\n\n\t_, err = provider.GetEndpoint(\"no-annotation-sandbox\")\n\tassert.Error(t, err)\n\tassert.True(t, errors.Is(err, ErrSandboxNotReady), \"Should return ErrSandboxNotReady\")\n\tassert.Contains(t, err.Error(), \"has no annotations\")\n}\n\n// TestBatchSandboxProvider_InvalidAnnotation tests sandbox with invalid annotation format\nfunc TestBatchSandboxProvider_InvalidAnnotation(t *testing.T) {\n\tnamespace := \"test-namespace\"\n\n\tbatchSandbox := &sandboxv1alpha1.BatchSandbox{\n\t\tObjectMeta: metav1.ObjectMeta{\n\t\t\tName: \"invalid-annotation-sandbox\",\n\t\t\tNamespace: namespace,\n\t\t\tAnnotations: map[string]string{\n\t\t\t\tutils.AnnotationEndpoints: `invalid-json`,\n\t\t\t},\n\t\t},\n\t\tSpec: sandboxv1alpha1.BatchSandboxSpec{\n\t\t\tReplicas: ptr(int32(1)),\n\t\t},\n\t\tStatus: sandboxv1alpha1.BatchSandboxStatus{\n\t\t\tReplicas: 1,\n\t\t\tReady: 1,\n\t\t},\n\t}\n\n\tfakeClient := fakeclientset.NewSimpleClientset(batchSandbox)\n\tinformerFactory := informers.NewSharedInformerFactoryWithOptions(\n\t\tfakeClient,\n\t\ttime.Second*30,\n\t\tinformers.WithNamespace(namespace),\n\t)\n\n\tbatchSandboxInformer := informerFactory.Sandbox().V1alpha1().BatchSandboxes()\n\n\tprovider := &BatchSandboxProvider{\n\t\tinformerFactory: informerFactory,\n\t\tlister: batchSandboxInformer.Lister(),\n\t\tinformerSynced: batchSandboxInformer.Informer().HasSynced,\n\t\tnamespace: namespace,\n\t}\n\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err)\n\n\t// Manually add object to informer cache\n\terr = batchSandboxInformer.Informer().GetStore().Add(batchSandbox)\n\tassert.NoError(t, err)\n\n\t_, err = provider.GetEndpoint(\"invalid-annotation-sandbox\")\n\tassert.Error(t, err)\n\tassert.True(t, errors.Is(err, ErrSandboxNotReady), \"Should return ErrSandboxNotReady\")\n\tassert.Contains(t, err.Error(), \"failed to parse\")\n}\n\n// TestBatchSandboxProvider_DynamicUpdate tests adding object after informer starts\nfunc TestBatchSandboxProvider_DynamicUpdate(t *testing.T) {\n\tnamespace := \"test-namespace\"\n\n\tfakeClient := fakeclientset.NewSimpleClientset()\n\tinformerFactory := informers.NewSharedInformerFactoryWithOptions(\n\t\tfakeClient,\n\t\ttime.Second*30,\n\t\tinformers.WithNamespace(namespace),\n\t)\n\n\tbatchSandboxInformer := informerFactory.Sandbox().V1alpha1().BatchSandboxes()\n\n\tprovider := &BatchSandboxProvider{\n\t\tinformerFactory: informerFactory,\n\t\tlister: batchSandboxInformer.Lister(),\n\t\tinformerSynced: batchSandboxInformer.Informer().HasSynced,\n\t\tnamespace: namespace,\n\t}\n\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err)\n\n\t// Initially no sandbox exists\n\t_, err = provider.GetEndpoint(\"dynamic-sandbox\")\n\tassert.Error(t, err)\n\tassert.True(t, errors.Is(err, ErrSandboxNotFound), \"Should return ErrSandboxNotFound\")\n\tassert.Contains(t, err.Error(), \"not found\")\n\n\t// Add a new BatchSandbox\n\tnewBatchSandbox := &sandboxv1alpha1.BatchSandbox{\n\t\tObjectMeta: metav1.ObjectMeta{\n\t\t\tName: \"dynamic-sandbox\",\n\t\t\tNamespace: namespace,\n\t\t\tAnnotations: map[string]string{\n\t\t\t\tutils.AnnotationEndpoints: `[\"10.0.0.100\"]`,\n\t\t\t},\n\t\t},\n\t\tSpec: sandboxv1alpha1.BatchSandboxSpec{\n\t\t\tReplicas: ptr(int32(1)),\n\t\t},\n\t\tStatus: sandboxv1alpha1.BatchSandboxStatus{\n\t\t\tReplicas: 1,\n\t\t\tReady: 1,\n\t\t},\n\t}\n\n\t_, err = fakeClient.SandboxV1alpha1().BatchSandboxes(namespace).Create(\n\t\tcontext.Background(), newBatchSandbox, metav1.CreateOptions{})\n\tassert.NoError(t, err)\n\n\t// Wait for informer to pick up the change\n\tassert.Eventually(t, func() bool {\n\t\tendpoint, err := provider.GetEndpoint(\"dynamic-sandbox\")\n\t\treturn err == nil && endpoint == \"10.0.0.100\"\n\t}, 3*time.Second, 100*time.Millisecond, \"Informer should eventually sync the new object\")\n}\n\n// TestBatchSandboxProvider_StartCacheSyncFailure tests cache sync timeout\nfunc TestBatchSandboxProvider_StartCacheSyncFailure(t *testing.T) {\n\tnamespace := \"test-namespace\"\n\n\tfakeClient := fakeclientset.NewSimpleClientset()\n\tinformerFactory := informers.NewSharedInformerFactoryWithOptions(\n\t\tfakeClient,\n\t\ttime.Second*30,\n\t\tinformers.WithNamespace(namespace),\n\t)\n\n\tbatchSandboxInformer := informerFactory.Sandbox().V1alpha1().BatchSandboxes()\n\n\tprovider := &BatchSandboxProvider{\n\t\tinformerFactory: informerFactory,\n\t\tlister: batchSandboxInformer.Lister(),\n\t\tinformerSynced: batchSandboxInformer.Informer().HasSynced,\n\t\tnamespace: namespace,\n\t}\n\n\t// Create a context that expires immediately\n\tctx, cancel := context.WithTimeout(context.Background(), 1*time.Nanosecond)\n\tdefer cancel()\n\n\t// Wait for context to expire\n\ttime.Sleep(10 * time.Millisecond)\n\n\terr := provider.Start(ctx)\n\tassert.Error(t, err, \"Should fail when cache sync times out\")\n\tassert.Contains(t, err.Error(), \"failed to sync\")\n}\n\n// TestBatchSandboxProvider_GetEndpointNonNotFoundError tests non-IsNotFound K8s errors\nfunc TestBatchSandboxProvider_GetEndpointNonNotFoundError(t *testing.T) {\n\tnamespace := \"test-namespace\"\n\n\t// Create a sandbox with Ready status but missing endpoint annotation\n\tbatchSandbox := &sandboxv1alpha1.BatchSandbox{\n\t\tObjectMeta: metav1.ObjectMeta{\n\t\t\tName: \"missing-endpoint-sandbox\",\n\t\t\tNamespace: namespace,\n\t\t\tAnnotations: map[string]string{\n\t\t\t\tutils.AnnotationEndpoints: `[\"10.0.0.1\"]`,\n\t\t\t},\n\t\t},\n\t\tSpec: sandboxv1alpha1.BatchSandboxSpec{\n\t\t\tReplicas: ptr(int32(1)),\n\t\t},\n\t\tStatus: sandboxv1alpha1.BatchSandboxStatus{\n\t\t\tReplicas: 1,\n\t\t\tReady: 1,\n\t\t},\n\t}\n\n\tfakeClient := fakeclientset.NewSimpleClientset(batchSandbox)\n\tinformerFactory := informers.NewSharedInformerFactoryWithOptions(\n\t\tfakeClient,\n\t\ttime.Second*30,\n\t\tinformers.WithNamespace(namespace),\n\t)\n\n\tbatchSandboxInformer := informerFactory.Sandbox().V1alpha1().BatchSandboxes()\n\n\tprovider := &BatchSandboxProvider{\n\t\tinformerFactory: informerFactory,\n\t\tlister: batchSandboxInformer.Lister(),\n\t\tinformerSynced: batchSandboxInformer.Informer().HasSynced,\n\t\tnamespace: namespace,\n\t}\n\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\terr := provider.Start(ctx)\n\tassert.NoError(t, err)\n\n\t// Manually add object to informer cache\n\terr = batchSandboxInformer.Informer().GetStore().Add(batchSandbox)\n\tassert.NoError(t, err)\n\n\t// Should successfully get endpoint\n\tendpoint, err := provider.GetEndpoint(\"missing-endpoint-sandbox\")\n\tassert.NoError(t, err)\n\tassert.Equal(t, \"10.0.0.1\", endpoint)\n}\n\n// ptr is a helper function to create int32 pointer\nfunc ptr(i int32) *int32 {\n\treturn &i\n}\n" }, { "path": "components/ingress/pkg/sandbox/errors_test.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage sandbox\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"testing\"\n)\n\n// Ensure wrapping ErrSandboxNotReady keeps errors.Is behavior.\nfunc TestErrSandboxNotReadyWrapping(t *testing.T) {\n\twrapped := fmt.Errorf(\"%w: custom detail\", ErrSandboxNotReady)\n\n\tif !errors.Is(wrapped, ErrSandboxNotReady) {\n\t\tt.Fatalf(\"expected errors.Is to match ErrSandboxNotReady, got false; err=%v\", wrapped)\n\t}\n}\n" }, { "path": "components/ingress/pkg/sandbox/factory.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage sandbox\n\nimport (\n\t\"fmt\"\n\t\"time\"\n\n\t\"k8s.io/client-go/rest\"\n)\n\n// DefaultProviderFactory is the default implementation of ProviderFactory\ntype DefaultProviderFactory struct {\n\tconfig *rest.Config\n\tnamespace string\n\tresyncPeriod time.Duration\n}\n\n// NewProviderFactory creates a new DefaultProviderFactory\nfunc NewProviderFactory(config *rest.Config, namespace string, resyncPeriod time.Duration) *DefaultProviderFactory {\n\treturn &DefaultProviderFactory{\n\t\tconfig: config,\n\t\tnamespace: namespace,\n\t\tresyncPeriod: resyncPeriod,\n\t}\n}\n\n// CreateProvider creates a Provider instance based on the provider type\nfunc (f *DefaultProviderFactory) CreateProvider(providerType ProviderType) (Provider, error) {\n\tswitch providerType {\n\tcase ProviderTypeBatchSandbox:\n\t\treturn NewBatchSandboxProvider(f.config, f.namespace, f.resyncPeriod), nil\n\tcase ProviderTypeAgentSandbox:\n\t\treturn NewAgentSandboxProvider(f.config, f.namespace, f.resyncPeriod), nil\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"unsupported provider type: %s\", providerType)\n\t}\n}\n" }, { "path": "components/ingress/pkg/sandbox/provider.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage sandbox\n\nimport (\n\t\"context\"\n\t\"errors\"\n)\n\ntype ProviderType string\n\nconst (\n\tProviderTypeBatchSandbox ProviderType = \"batchsandbox\"\n\tProviderTypeAgentSandbox ProviderType = \"agent-sandbox\"\n)\n\nfunc (tpy ProviderType) String() string { return string(tpy) }\n\n// Standard errors for Provider operations\nvar (\n\t// ErrSandboxNotFound indicates the sandbox resource does not exist\n\tErrSandboxNotFound = errors.New(\"sandbox not found\")\n\n\t// ErrSandboxNotReady indicates the sandbox exists but is not ready\n\t// This includes: not enough ready replicas, missing endpoints, invalid configuration\n\tErrSandboxNotReady = errors.New(\"sandbox not ready\")\n)\n\n// Provider defines the interface for sandbox resource providers\n// Implementations include BatchSandboxProvider, AgentSandboxProvider, etc.\ntype Provider interface {\n\t// GetEndpoint retrieves the IP address for a sandbox by its id/name\n\t// The namespace is determined by the provider's configuration\n\t// Returns the first available IP from the endpoints annotation\n\t// Returns error if sandbox not found or no endpoints available\n\t// Note: This is a local cache query, no network I/O involved\n\tGetEndpoint(sandboxId string) (string, error)\n\n\t// Start initializes and starts the provider's informer cache\n\t// Waits for cache sync before returning\n\t// Must be called before using GetEndpoint\n\tStart(ctx context.Context) error\n}\n\n// ProviderFactory creates a Provider instance based on the provider type\ntype ProviderFactory interface {\n\tCreateProvider(providerType ProviderType) (Provider, error)\n}\n" }, { "path": "components/internal/go.mod", "content": "module github.com/alibaba/opensandbox/internal\n\ngo 1.24.0\n\nrequire go.uber.org/zap v1.27.0\n\nrequire go.uber.org/multierr v1.10.0 // indirect\n" }, { "path": "components/internal/go.sum", "content": "github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=\ngithub.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=\ngithub.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=\ngithub.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=\ngithub.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=\ngithub.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=\ngo.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=\ngo.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=\ngo.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=\ngo.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=\ngo.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=\ngo.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=\ngopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=\ngopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=\n" }, { "path": "components/internal/logger/logger.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage logger\n\n// Field is a structured logging key/value pair.\ntype Field struct {\n\tKey string\n\tValue any\n}\n\n// Logger defines the minimal logging surface shared by components.\n// - Formatted levels: Debugf/Infof/Warnf/Errorf\n// - With: attach structured fields to derived logger\n// - Named: derive a sub-logger with name\n// - Sync: flush buffers (no-op for implementations that don't buffer)\ntype Logger interface {\n\tDebugf(template string, args ...any)\n\tInfof(template string, args ...any)\n\tWarnf(template string, args ...any)\n\tErrorf(template string, args ...any)\n\tWith(fields ...Field) Logger\n\tNamed(name string) Logger\n\tSync() error\n}\n" }, { "path": "components/internal/logger/zap.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage logger\n\nimport (\n\t\"os\"\n\t\"strings\"\n\n\t\"go.uber.org/zap\"\n\t\"go.uber.org/zap/zapcore\"\n)\n\nconst envLogOutput = \"OPENSANDBOX_LOG_OUTPUT\"\n\n// Config is the minimal configuration to align execd/ingress defaults.\n// - JSON encoding, ISO8601 time\n// - Caller/stacktrace disabled\n// - Stdout as default output\n// - Level defaults to info\ntype Config struct {\n\tLevel string // debug|info|warn|error|fatal (default: info)\n\tOutputPaths []string // default: stdout\n\tErrorOutputPaths []string // default: OutputPaths\n}\n\n// New creates a zap-backed Logger with the provided config.\nfunc New(cfg Config) (Logger, error) {\n\tcfg = applyEnvOutputs(cfg)\n\n\tzapCfg := zap.NewProductionConfig()\n\tzapCfg.Level = zap.NewAtomicLevelAt(parseLevel(cfg.Level))\n\tzapCfg.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder\n\tzapCfg.EncoderConfig.CallerKey = \"\"\n\tzapCfg.DisableCaller = true\n\tzapCfg.DisableStacktrace = true\n\tzapCfg.EncoderConfig.StacktraceKey = \"\"\n\n\tzapCfg.OutputPaths = cfg.OutputPaths\n\tzapCfg.ErrorOutputPaths = cfg.ErrorOutputPaths\n\n\tbase, err := zapCfg.Build()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn &zapLogger{base: base, sugar: base.Sugar()}, nil\n}\n\n// MustNew is a convenience helper that panics on error.\nfunc MustNew(cfg Config) Logger {\n\tl, err := New(cfg)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treturn l\n}\n\n// AsZapSugared returns the underlying zap SugaredLogger when available.\nfunc AsZapSugared(l Logger) (*zap.SugaredLogger, bool) {\n\tzl, ok := l.(*zapLogger)\n\tif !ok {\n\t\treturn nil, false\n\t}\n\treturn zl.sugar, true\n}\n\ntype zapLogger struct {\n\tbase *zap.Logger\n\tsugar *zap.SugaredLogger\n}\n\nfunc (l *zapLogger) Debugf(template string, args ...any) {\n\tl.sugar.Debugf(template, args...)\n}\n\nfunc (l *zapLogger) Infof(template string, args ...any) {\n\tl.sugar.Infof(template, args...)\n}\n\nfunc (l *zapLogger) Warnf(template string, args ...any) {\n\tl.sugar.Warnf(template, args...)\n}\n\nfunc (l *zapLogger) Errorf(template string, args ...any) {\n\tl.sugar.Errorf(template, args...)\n}\n\nfunc (l *zapLogger) With(fields ...Field) Logger {\n\tif len(fields) == 0 {\n\t\treturn l\n\t}\n\tzfs := make([]zap.Field, 0, len(fields))\n\tfor _, f := range fields {\n\t\tzfs = append(zfs, zap.Any(f.Key, f.Value))\n\t}\n\tnb := l.base.With(zfs...)\n\treturn &zapLogger{base: nb, sugar: nb.Sugar()}\n}\n\nfunc (l *zapLogger) Named(name string) Logger {\n\tnb := l.base.Named(name)\n\treturn &zapLogger{base: nb, sugar: nb.Sugar()}\n}\n\nfunc (l *zapLogger) Sync() error {\n\treturn l.base.Sync()\n}\n\nfunc parseLevel(level string) zapcore.Level {\n\tswitch strings.ToLower(level) {\n\tcase \"debug\":\n\t\treturn zapcore.DebugLevel\n\tcase \"warn\", \"warning\":\n\t\treturn zapcore.WarnLevel\n\tcase \"error\":\n\t\treturn zapcore.ErrorLevel\n\tcase \"fatal\":\n\t\treturn zapcore.FatalLevel\n\tdefault:\n\t\treturn zapcore.InfoLevel\n\t}\n}\n\nfunc applyEnvOutputs(cfg Config) Config {\n\tenvVal := strings.TrimSpace(os.Getenv(envLogOutput))\n\tif len(cfg.OutputPaths) == 0 {\n\t\tif envVal != \"\" {\n\t\t\tcfg.OutputPaths = splitAndTrim(envVal)\n\t\t} else {\n\t\t\tcfg.OutputPaths = []string{\"stdout\"}\n\t\t}\n\t}\n\tif len(cfg.ErrorOutputPaths) == 0 {\n\t\t// Default error output matches output paths.\n\t\tcfg.ErrorOutputPaths = cfg.OutputPaths\n\t}\n\treturn cfg\n}\n\nfunc splitAndTrim(s string) []string {\n\tparts := strings.Split(s, \",\")\n\tout := make([]string, 0, len(parts))\n\tfor _, p := range parts {\n\t\tif v := strings.TrimSpace(p); v != \"\" {\n\t\t\tout = append(out, v)\n\t\t}\n\t}\n\treturn out\n}\n" }, { "path": "components/internal/version/version.go", "content": "// Copyright 2026 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage version\n\nimport (\n\t\"fmt\"\n\t\"runtime\"\n)\n\n// Package values are typically overridden at build time via -ldflags.\nvar (\n\t// Version is the component version.\n\tVersion = \"dirty\"\n\t// BuildTime is when the binary was built.\n\tBuildTime = \"assigned-at-build-time\"\n\t// GitCommit is the commit id used to build the binary.\n\tGitCommit = \"assigned-at-build-time\"\n)\n\n// EchoVersion prints build info for the given component name (e.g. \"OpenSandbox Ingress\", \"OpenSandbox Execd\").\n// All components can use this by passing their display name.\nfunc EchoVersion(componentName string) {\n\tfmt.Println(\"=====================================================\")\n\tfmt.Printf(\" %s\\n\", componentName)\n\tfmt.Println(\"-----------------------------------------------------\")\n\tfmt.Printf(\" Version : %s\\n\", Version)\n\tfmt.Printf(\" Git Commit : %s\\n\", GitCommit)\n\tfmt.Printf(\" Build Time : %s\\n\", BuildTime)\n\tfmt.Printf(\" Go Version : %s\\n\", runtime.Version())\n\tfmt.Printf(\" Platform : %s/%s\\n\", runtime.GOOS, runtime.GOARCH)\n\tfmt.Println(\"=====================================================\")\n}\n" }, { "path": "docs/.nvmrc", "content": "22\n" }, { "path": "docs/.vitepress/config.mts", "content": "import { defineConfig } from \"vitepress\";\nimport { loadManifest } from \"./scripts/docs-manifest.mjs\";\n\nconst manifest = loadManifest();\nconst docsBase = process.env.DOCS_BASE || \"/\";\n\nexport default defineConfig({\n title: \"OpenSandbox\",\n description: \"OpenSandbox documentation site for users and developers\",\n head: [[\"link\", { rel: \"icon\", type: \"image/svg+xml\", href: \"/favicon.svg\" }]],\n cleanUrls: true,\n lastUpdated: true,\n base: docsBase,\n ignoreDeadLinks: [/^https?:\\/\\/localhost/, /\\/README$/, /\\/index$/, \"./contributing\"],\n srcExclude: [\"node_modules/**\", \"README_zh.md\", \"RELEASE_NOTE_TEMPLATE.md\"],\n rewrites: manifest.rewrites,\n themeConfig: {\n logo: \"/assets/logo.svg\",\n search: {\n provider: \"local\",\n },\n socialLinks: [{ icon: \"github\", link: \"https://github.com/alibaba/OpenSandbox\" }],\n nav: manifest.nav.en,\n sidebar: {\n ...manifest.sidebar.en,\n ...manifest.sidebar.zh,\n },\n outline: {\n level: [2, 3],\n },\n },\n locales: {\n root: {\n label: \"English\",\n lang: \"en-US\",\n themeConfig: {\n nav: manifest.nav.en,\n },\n },\n zh: {\n label: \"็ฎ€ไฝ“ไธญๆ–‡\",\n lang: \"zh-CN\",\n themeConfig: {\n nav: manifest.nav.zh,\n },\n },\n },\n});\n" }, { "path": "docs/.vitepress/scripts/docs-manifest.mjs", "content": "import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\nconst repoRoot = path.resolve(__dirname, \"../../../\");\nconst docsRoot = path.join(repoRoot, \"docs\");\nconst generatedRoot = path.join(docsRoot, \"generated\");\nconst manifestPath = path.join(docsRoot, \".vitepress\", \"generated\", \"manifest.json\");\n\nconst blobBaseUrl = \"https://github.com/alibaba/OpenSandbox/blob/main\";\nconst treeBaseUrl = \"https://github.com/alibaba/OpenSandbox/tree/main\";\nconst rawBaseUrl = \"https://raw.githubusercontent.com/alibaba/OpenSandbox/main\";\n\nconst ignoredDirNames = new Set([\n \".git\",\n \".github\",\n \"node_modules\",\n \".vitepress\",\n \".pytest_cache\",\n \"generated\",\n \".venv\",\n \"venv\",\n \"__pycache__\",\n \"dist\",\n \"build\",\n \"target\",\n \"bin\",\n]);\nconst zhReadmePattern = /^README(?:[-_](?:zh|zh-cn|zh_cn))?\\.md$/i;\nconst standardReadmePattern = /^README\\.md$/i;\n\nconst sectionDefinitions = [\n {\n id: \"modules\",\n scanRoots: [\"server\", \"components\", \"sandboxes\", \"kubernetes\", \"specs\", \"sdks\"],\n includeDevelopment: true,\n },\n {\n id: \"examples\",\n scanRoots: [\"examples\"],\n includeDevelopment: false,\n },\n {\n id: \"community\",\n scanRoots: [\"oseps\"],\n includeDevelopment: false,\n },\n];\n\nconst manualEntries = [\n {\n key: \"guide-home\",\n sectionId: \"overview\",\n slug: \"overview/home\",\n enPath: \"README.md\",\n zhPath: \"docs/README_zh.md\",\n titleEn: \"OpenSandbox\",\n titleZh: \"OpenSandbox\",\n },\n {\n key: \"guide-architecture\",\n sectionId: \"overview\",\n slug: \"overview/architecture\",\n enPath: \"docs/architecture.md\",\n zhPath: null,\n titleEn: \"Architecture\",\n titleZh: \"ๆžถๆž„่ฎพ่ฎก\",\n },\n {\n key: \"guide-network\",\n sectionId: \"modules\",\n slug: \"design/single-host-network\",\n enPath: \"docs/single_host_network.md\",\n zhPath: null,\n titleEn: \"Single Host Network\",\n titleZh: \"ๅ•ๆœบๅœบๆ™ฏ็ฝ‘็ปœ่ฎพ่ฎก\",\n },\n {\n key: \"community-contributing\",\n sectionId: \"community\",\n slug: \"community/contributing\",\n enPath: \"CONTRIBUTING.md\",\n zhPath: null,\n titleEn: \"Contributing\",\n titleZh: \"ๅ‚ไธŽ่ดก็Œฎ\",\n },\n {\n key: \"community-code-of-conduct\",\n sectionId: \"community\",\n slug: \"community/code-of-conduct\",\n enPath: \"CODE_OF_CONDUCT.md\",\n zhPath: null,\n titleEn: \"Code of Conduct\",\n titleZh: \"่กŒไธบๅ‡†ๅˆ™\",\n },\n];\n\nconst moduleGroupLabels = {\n en: {\n sdks: \"SDKs\",\n specs: \"Specs & API\",\n server: \"Server\",\n components: \"Components\",\n sandboxes: \"Sandboxes\",\n kubernetes: \"Kubernetes\",\n design: \"Design\",\n },\n zh: {\n sdks: \"SDKs\",\n specs: \"Specs & API\",\n server: \"Server\",\n components: \"Components\",\n sandboxes: \"Sandboxes\",\n kubernetes: \"Kubernetes\",\n design: \"่ฎพ่ฎก\",\n },\n};\n\nconst communityGroupLabels = {\n en: {\n community: \"Community\",\n oseps: \"OSEPs\",\n },\n zh: {\n community: \"็คพๅŒบ\",\n oseps: \"OSEPs\",\n },\n};\n\nconst shortTitleByPath = {\n \"sdks/code-interpreter/javascript/README.md\": \"Code Interpreter JS SDK\",\n \"sdks/code-interpreter/kotlin/README.md\": \"Code Interpreter Kotlin SDK\",\n \"sdks/code-interpreter/python/README.md\": \"Code Interpreter Python SDK\",\n \"sdks/code-interpreter/csharp/README.md\": \"Code Interpreter C# SDK\",\n \"sdks/sandbox/javascript/README.md\": \"Sandbox JS SDK\",\n \"sdks/sandbox/kotlin/README.md\": \"Sandbox Kotlin SDK\",\n \"sdks/sandbox/python/README.md\": \"Sandbox Python SDK\",\n \"sdks/sandbox/csharp/README.md\": \"Sandbox C# SDK\",\n \"sdks/mcp/sandbox/python/README.md\": \"MCP Sandbox Python SDK\",\n \"cli/README.md\": \"CLI (Python)\",\n \"sdks/sandbox/kotlin/sandbox-api/build/generated/api/execd/README.md\": \"Sandbox Execd API (Kotlin)\",\n \"sdks/sandbox/kotlin/sandbox-api/build/generated/api/lifecycle/README.md\": \"Sandbox Lifecycle API (Kotlin)\",\n\n \"examples/agent-sandbox/README.md\": \"Agent Sandbox\",\n \"examples/aio-sandbox/README.md\": \"AIO Sandbox\",\n \"examples/chrome/README.md\": \"Chrome\",\n \"examples/claude-code/README.md\": \"Claude Code\",\n \"examples/code-interpreter/README.md\": \"Code Interpreter\",\n \"examples/codex-cli/README.md\": \"Codex CLI\",\n \"examples/desktop/README.md\": \"Desktop (VNC)\",\n \"examples/gemini-cli/README.md\": \"Gemini CLI\",\n \"examples/google-adk/README.md\": \"Google ADK\",\n \"examples/host-volume-mount/README.md\": \"Host Volume Mount\",\n \"examples/langgraph/README.md\": \"LangGraph\",\n \"examples/playwright/README.md\": \"Playwright\",\n \"examples/README.md\": \"Examples Overview\",\n \"examples/rl-training/README.md\": \"RL Training\",\n \"examples/vscode/README.md\": \"VS Code\",\n\n \"server/README.md\": \"Server\",\n \"server/DEVELOPMENT.md\": \"Server Development\",\n \"components/ingress/README.md\": \"Ingress\",\n \"components/ingress/DEVELOPMENT.md\": \"Ingress Development\",\n \"components/egress/README.md\": \"Egress Sidecar\",\n \"components/execd/README.md\": \"execd\",\n \"components/execd/DEVELOPMENT.md\": \"execd Development\",\n \"sandboxes/code-interpreter/README.md\": \"Code Interpreter Runtime\",\n \"kubernetes/README.md\": \"Kubernetes Controller\",\n \"kubernetes/examples/task-executor/README.md\": \"Task Executor\",\n \"kubernetes/examples/controller/README.md\": \"Controller Example\",\n \"oseps/README.md\": \"OSEP Overview\",\n};\n\nconst shortTitleByPathZh = {\n \"sdks/code-interpreter/javascript/README.md\": \"ไปฃ็ ่งฃ้‡Šๅ™จ JS SDK\",\n \"sdks/code-interpreter/kotlin/README.md\": \"ไปฃ็ ่งฃ้‡Šๅ™จ Kotlin SDK\",\n \"sdks/code-interpreter/python/README.md\": \"ไปฃ็ ่งฃ้‡Šๅ™จ Python SDK\",\n \"sdks/code-interpreter/csharp/README.md\": \"ไปฃ็ ่งฃ้‡Šๅ™จ C# SDK\",\n \"sdks/sandbox/javascript/README.md\": \"ๆฒ™็ฎฑ JS SDK\",\n \"sdks/sandbox/kotlin/README.md\": \"ๆฒ™็ฎฑ Kotlin SDK\",\n \"sdks/sandbox/python/README.md\": \"ๆฒ™็ฎฑ Python SDK\",\n \"sdks/sandbox/csharp/README.md\": \"ๆฒ™็ฎฑ C# SDK\",\n \"sdks/mcp/sandbox/python/README.md\": \"MCP ๆฒ™็ฎฑ Python SDK\",\n \"cli/README.md\": \"CLI๏ผˆPython๏ผ‰\",\n \"sdks/sandbox/kotlin/sandbox-api/build/generated/api/execd/README.md\": \"ๆฒ™็ฎฑ Execd API๏ผˆKotlin๏ผ‰\",\n \"sdks/sandbox/kotlin/sandbox-api/build/generated/api/lifecycle/README.md\": \"ๆฒ™็ฎฑ็”Ÿๅ‘ฝๅ‘จๆœŸ API๏ผˆKotlin๏ผ‰\",\n\n \"examples/agent-sandbox/README.md\": \"Agent Sandbox\",\n \"examples/aio-sandbox/README.md\": \"AIO ๆฒ™็ฎฑ\",\n \"examples/chrome/README.md\": \"Chrome\",\n \"examples/claude-code/README.md\": \"Claude Code\",\n \"examples/code-interpreter/README.md\": \"ไปฃ็ ่งฃ้‡Šๅ™จ\",\n \"examples/codex-cli/README.md\": \"Codex CLI\",\n \"examples/desktop/README.md\": \"ๆกŒ้ข็Žฏๅขƒ๏ผˆVNC๏ผ‰\",\n \"examples/gemini-cli/README.md\": \"Gemini CLI\",\n \"examples/google-adk/README.md\": \"Google ADK\",\n \"examples/host-volume-mount/README.md\": \"ๅฎฟไธปๆœบ็›ฎๅฝ•ๆŒ‚่ฝฝ\",\n \"examples/langgraph/README.md\": \"LangGraph\",\n \"examples/playwright/README.md\": \"Playwright\",\n \"examples/README.md\": \"็คบไพ‹ๆ€ป่งˆ\",\n \"examples/rl-training/README.md\": \"ๅผบๅŒ–ๅญฆไน ่ฎญ็ปƒ\",\n \"examples/vscode/README.md\": \"VS Code\",\n\n \"server/README.md\": \"Server\",\n \"server/DEVELOPMENT.md\": \"Server ๅผ€ๅ‘ๆŒ‡ๅ—\",\n \"components/ingress/README.md\": \"Ingress\",\n \"components/ingress/DEVELOPMENT.md\": \"Ingress ๅผ€ๅ‘ๆŒ‡ๅ—\",\n \"components/egress/README.md\": \"Egress Sidecar\",\n \"components/execd/README.md\": \"execd\",\n \"components/execd/DEVELOPMENT.md\": \"execd ๅผ€ๅ‘ๆŒ‡ๅ—\",\n \"sandboxes/code-interpreter/README.md\": \"ไปฃ็ ่งฃ้‡Šๅ™จ่ฟ่กŒๆ—ถ\",\n \"kubernetes/README.md\": \"Kubernetes ๆŽงๅˆถๅ™จ\",\n \"kubernetes/examples/task-executor/README.md\": \"Task Executor\",\n \"kubernetes/examples/controller/README.md\": \"Controller ็คบไพ‹\",\n \"oseps/README.md\": \"OSEP ๆ€ป่งˆ\",\n};\n\nfunction ensureDir(dirPath) {\n fs.mkdirSync(dirPath, { recursive: true });\n}\n\nfunction rmIfExists(targetPath) {\n if (fs.existsSync(targetPath)) {\n fs.rmSync(targetPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 80 });\n }\n}\n\nfunction walkMarkdownFiles(absDirPath, acc = []) {\n const entries = fs.readdirSync(absDirPath, { withFileTypes: true });\n for (const entry of entries) {\n if (ignoredDirNames.has(entry.name)) {\n continue;\n }\n const absPath = path.join(absDirPath, entry.name);\n if (entry.isDirectory()) {\n walkMarkdownFiles(absPath, acc);\n continue;\n }\n if (!entry.isFile()) {\n continue;\n }\n if (entry.name.endsWith(\".md\")) {\n acc.push(absPath);\n }\n }\n return acc;\n}\n\nfunction shouldIgnoreRepoPath(repoRelPath) {\n const normalized = repoRelPath.replaceAll(\"\\\\\", \"/\");\n const denylistFragments = [\n \"/.venv/\",\n \"/venv/\",\n \"/node_modules/\",\n \"/docs/.vitepress/\",\n \"/docs/generated/\",\n \"/.pytest_cache/\",\n \"/__pycache__/\",\n \"/dist/\",\n \"/build/\",\n \"/target/\",\n \"/bin/\",\n ];\n return denylistFragments.some((fragment) => normalized.includes(fragment));\n}\n\nfunction toRepoRelative(absPath) {\n return path.relative(repoRoot, absPath).replaceAll(path.sep, \"/\");\n}\n\nfunction readHeadingTitle(absPath, fallbackTitle) {\n if (!fs.existsSync(absPath)) {\n return fallbackTitle;\n }\n const content = fs.readFileSync(absPath, \"utf8\");\n const lines = content.split(/\\r?\\n/);\n let inFence = false;\n for (const line of lines) {\n const trimmed = line.trimStart();\n if (trimmed.startsWith(\"```\")) {\n inFence = !inFence;\n continue;\n }\n if (inFence) {\n continue;\n }\n const matched = trimmed.match(/^#{1,3}\\s+(.+)$/);\n if (matched) {\n return matched[1].trim();\n }\n }\n return fallbackTitle;\n}\n\nfunction normalizeTitleWhitespace(title) {\n return title.replace(/\\s+/g, \" \").trim();\n}\n\nfunction shortenOsepTitle(repoRelPath, title, locale = \"en\") {\n const match = repoRelPath.match(/^oseps\\/(0\\d{3})-(.+)\\.md$/i);\n if (!match) {\n return title;\n }\n const number = match[1];\n const slug = match[2].toLowerCase();\n if (locale === \"zh\") {\n if (slug.includes(\"fqdn\") && slug.includes(\"egress\")) {\n return `OSEP-${number}: FQDN ๅ‡บๅฃ่ฎฟ้—ฎๆŽงๅˆถ`;\n }\n if (slug.includes(\"agent-sandbox\") || slug.includes(\"kubernetes-sigs\")) {\n return `OSEP-${number}: Kubernetes Agent Sandbox ๆ”ฏๆŒ`;\n }\n if (slug.includes(\"volume\")) {\n return `OSEP-${number}: Volume ไธŽ VolumeBinding ๆ”ฏๆŒ`;\n }\n }\n if (slug.includes(\"fqdn\") && slug.includes(\"egress\")) {\n return `OSEP-${number}: FQDN Egress Control`;\n }\n if (slug.includes(\"agent-sandbox\") || slug.includes(\"kubernetes-sigs\")) {\n return `OSEP-${number}: Agent Sandbox on Kubernetes`;\n }\n if (slug.includes(\"volume\")) {\n return `OSEP-${number}: Volume & VolumeBinding Support`;\n }\n const readable = slug\n .split(\"-\")\n .map((part) => (part.length <= 3 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1)))\n .join(\" \");\n return `OSEP-${number}: ${readable}`;\n}\n\nfunction shortenTitleByRule(title) {\n let next = normalizeTitleWhitespace(title);\n next = next.replace(/^Alibaba\\s+/i, \"\");\n next = next.replace(/^OpenSandbox\\s+/i, \"\");\n next = next.replace(/\\bJavaScript\\/TypeScript\\b/g, \"JS\");\n next = next.replace(/\\bJava\\/Kotlin\\b/g, \"Kotlin\");\n next = next.replace(/\\s+Example$/i, \"\");\n next = next.replace(/\\s+SDK for /i, \" \");\n return normalizeTitleWhitespace(next);\n}\n\nfunction shortenTitleByRuleZh(title) {\n let next = normalizeTitleWhitespace(title);\n next = next.replace(/^Alibaba\\s+/i, \"\");\n next = next.replace(/^OpenSandbox\\s+/i, \"\");\n next = next.replace(/\\bJavaScript\\/TypeScript\\b/g, \"JS\");\n next = next.replace(/\\bJava\\/Kotlin\\b/g, \"Kotlin\");\n next = next.replace(/\\s+Example$/i, \" ็คบไพ‹\");\n next = next.replace(/\\s+SDK for /i, \" \");\n return normalizeTitleWhitespace(next);\n}\n\nfunction getShortTitle(repoRelPath, currentTitle, locale = \"en\") {\n if (locale === \"zh\" && shortTitleByPathZh[repoRelPath]) {\n return shortTitleByPathZh[repoRelPath];\n }\n if (locale !== \"zh\" && shortTitleByPath[repoRelPath]) {\n return shortTitleByPath[repoRelPath];\n }\n if (/^oseps\\/0\\d{3}-.+\\.md$/i.test(repoRelPath)) {\n return shortenOsepTitle(repoRelPath, currentTitle, locale);\n }\n if (locale === \"zh\") {\n return shortenTitleByRuleZh(currentTitle);\n }\n return shortenTitleByRule(currentTitle);\n}\n\nfunction toYamlString(value) {\n return `\"${String(value).replace(/\\\\/g, \"\\\\\\\\\").replace(/\"/g, '\\\\\"')}\"`;\n}\n\nfunction normalizeSlugFromPath(relPath) {\n const normalized = relPath.replaceAll(\"\\\\\", \"/\");\n const dirName = path.posix.dirname(normalized);\n const baseName = path.posix.basename(normalized);\n const lowerBase = baseName.toLowerCase();\n\n if (lowerBase === \"readme.md\" || zhReadmePattern.test(baseName)) {\n return dirName === \".\" ? \"overview/home\" : `${dirName}/readme`;\n }\n if (lowerBase === \"development.md\") {\n return `${dirName}/development`;\n }\n return normalized.replace(/\\.md$/i, \"\");\n}\n\nfunction resolveZhCandidate(repoRelPath, readmeCandidatesByDir) {\n const dir = path.posix.dirname(repoRelPath);\n const candidates = readmeCandidatesByDir.get(dir) ?? [];\n for (const candidate of candidates) {\n if (candidate.toLowerCase() !== \"readme.md\") {\n return `${dir}/${candidate}`;\n }\n }\n return null;\n}\n\nfunction buildGeneratedAssetPath(locale, routeSlug, resolvedRepoPath) {\n const normalized = resolvedRepoPath.replaceAll(\"\\\\\", \"/\");\n if (!normalized.startsWith(\"docs/assets/\")) {\n return null;\n }\n const generatedDir = path.posix.dirname(`generated/${locale}/${routeSlug}.md`);\n const assetPath = normalized.replace(/^docs\\//, \"\");\n let relativePath = path.posix.relative(generatedDir, assetPath);\n if (!relativePath || relativePath === \"\") {\n relativePath = \"./\";\n }\n if (!relativePath.startsWith(\".\") && !relativePath.startsWith(\"/\")) {\n relativePath = `./${relativePath}`;\n }\n return relativePath;\n}\n\nfunction normalizeLinkTarget(target, sourceDirRel, isImage, routeSlug, locale) {\n if (\n target.startsWith(\"http://\") ||\n target.startsWith(\"https://\") ||\n target.startsWith(\"mailto:\") ||\n target.startsWith(\"#\") ||\n target.startsWith(\"data:\") ||\n target.startsWith(\"/\")\n ) {\n return target;\n }\n\n const [rawPath, hashFragment] = target.split(\"#\");\n const resolvedPath = path.posix.normalize(path.posix.join(sourceDirRel, rawPath));\n const localAssetPath = isImage ? buildGeneratedAssetPath(locale, routeSlug, resolvedPath) : null;\n if (localAssetPath) {\n if (hashFragment) {\n return `${localAssetPath}#${hashFragment}`;\n }\n return localAssetPath;\n }\n\n const urlBase = isImage\n ? `${rawBaseUrl}/${resolvedPath}`\n : fs.existsSync(path.join(repoRoot, resolvedPath)) &&\n fs.statSync(path.join(repoRoot, resolvedPath)).isDirectory()\n ? `${treeBaseUrl}/${resolvedPath}`\n : `${blobBaseUrl}/${resolvedPath}`;\n\n if (hashFragment) {\n return `${urlBase}#${hashFragment}`;\n }\n return urlBase;\n}\n\nfunction rewriteRelativeLinks(markdown, sourceRelPath, routeSlug, locale) {\n const sourceDirRel = path.posix.dirname(sourceRelPath);\n\n const withMarkdownLinks = markdown.replace(\n /(!?)\\[([^\\]]*?)\\]\\(([^)]+)\\)/g,\n (_match, imageMark, text, linkValue) => {\n const trimmed = linkValue.trim();\n if (!trimmed) {\n return _match;\n }\n const firstSpace = trimmed.search(/\\s/);\n const target = firstSpace === -1 ? trimmed : trimmed.slice(0, firstSpace);\n const trailing = firstSpace === -1 ? \"\" : trimmed.slice(firstSpace);\n const rewrittenTarget = normalizeLinkTarget(target, sourceDirRel, imageMark === \"!\", routeSlug, locale);\n return `${imageMark}[${text}](${rewrittenTarget}${trailing})`;\n },\n );\n\n return withMarkdownLinks.replace(\n /]*?)src=([\"'])([^\"']+)\\2([^>]*)>/gi,\n (matched, before, quote, src, after) => {\n const rewritten = normalizeLinkTarget(src, sourceDirRel, true, routeSlug, locale);\n return ``;\n },\n );\n}\n\nfunction renderPageSource({ locale, title, sourceRelPath, routeSlug, passthrough = false }) {\n const sourceAbsPath = path.join(repoRoot, sourceRelPath);\n const sourceMarkdown = fs.readFileSync(sourceAbsPath, \"utf8\");\n const displayTitle = title || readHeadingTitle(sourceAbsPath, path.posix.basename(sourceRelPath, \".md\"));\n\n let body = sourceMarkdown;\n if (!passthrough) {\n body = rewriteRelativeLinks(sourceMarkdown, sourceRelPath, routeSlug, locale);\n }\n\n const sourceUrl = `${blobBaseUrl}/${sourceRelPath}`;\n const sourceNotice =\n locale === \"zh\"\n ? `> ๆญค้กตๅ†…ๅฎนๆฅ่‡ชไป“ๅบ“ๆบๆ–‡ไปถ๏ผš[\\`${sourceRelPath}\\`](${sourceUrl})`\n : `> This page is sourced from: [\\`${sourceRelPath}\\`](${sourceUrl})`;\n\n\n return `---\\ntitle: ${toYamlString(displayTitle)}\\n---\\n\\n${body}\\n\\n---\\n\\n${sourceNotice}\\n`;\n}\n\nfunction prettifyPathTitle(repoRelPath) {\n const dirPath = path.posix.dirname(repoRelPath);\n if (dirPath === \".\" || dirPath === \"docs\") {\n return \"Overview\";\n }\n return dirPath\n .split(\"/\")\n .map((part) =>\n part\n .replaceAll(\"-\", \" \")\n .replaceAll(\"_\", \" \")\n .replace(/\\b\\w/g, (ch) => ch.toUpperCase()),\n )\n .join(\" / \");\n}\n\nfunction collectAutoEntries() {\n const readmeCandidatesByDir = new Map();\n const entries = [];\n\n for (const section of sectionDefinitions) {\n for (const scanRoot of section.scanRoots) {\n const absScanRoot = path.join(repoRoot, scanRoot);\n if (!fs.existsSync(absScanRoot)) {\n continue;\n }\n const files = walkMarkdownFiles(absScanRoot);\n for (const absPath of files) {\n const repoRelPath = toRepoRelative(absPath);\n if (shouldIgnoreRepoPath(repoRelPath)) {\n continue;\n }\n const fileName = path.posix.basename(repoRelPath);\n const dirName = path.posix.dirname(repoRelPath);\n\n if (zhReadmePattern.test(fileName)) {\n const arr = readmeCandidatesByDir.get(dirName) ?? [];\n arr.push(fileName);\n readmeCandidatesByDir.set(dirName, arr);\n }\n }\n }\n }\n\n for (const section of sectionDefinitions) {\n for (const scanRoot of section.scanRoots) {\n const absScanRoot = path.join(repoRoot, scanRoot);\n if (!fs.existsSync(absScanRoot)) {\n continue;\n }\n const files = walkMarkdownFiles(absScanRoot);\n for (const absPath of files) {\n const repoRelPath = toRepoRelative(absPath);\n if (shouldIgnoreRepoPath(repoRelPath)) {\n continue;\n }\n const fileName = path.posix.basename(repoRelPath);\n if (zhReadmePattern.test(fileName) && !standardReadmePattern.test(fileName)) {\n continue;\n }\n\n const isReadme = standardReadmePattern.test(fileName);\n const isDevelopment = fileName === \"DEVELOPMENT.md\";\n const isOsepDoc = section.id === \"community\" && /^0\\d{3}-.+\\.md$/i.test(fileName);\n if (!isReadme && !(section.includeDevelopment && isDevelopment) && !isOsepDoc) {\n continue;\n }\n\n const zhCandidate = isReadme ? resolveZhCandidate(repoRelPath, readmeCandidatesByDir) : null;\n const entryKey = `auto:${section.id}:${repoRelPath}`;\n const slug = normalizeSlugFromPath(repoRelPath);\n const titleFallback = isDevelopment ? `${prettifyPathTitle(repoRelPath)} Development` : prettifyPathTitle(repoRelPath);\n entries.push({\n key: entryKey,\n sectionId: section.id,\n slug,\n enPath: repoRelPath,\n zhPath: zhCandidate,\n titleEn: getShortTitle(repoRelPath, readHeadingTitle(absPath, titleFallback), \"en\"),\n titleZh: getShortTitle(\n repoRelPath,\n readHeadingTitle(\n zhCandidate ? path.join(repoRoot, zhCandidate) : absPath,\n readHeadingTitle(absPath, titleFallback),\n ),\n \"zh\",\n ),\n });\n }\n }\n }\n\n const unique = new Map();\n for (const item of entries) {\n if (!unique.has(item.key)) {\n unique.set(item.key, item);\n }\n }\n return [...unique.values()].sort((a, b) => a.slug.localeCompare(b.slug));\n}\n\nfunction buildEntries() {\n const autoEntries = collectAutoEntries();\n const all = [...manualEntries, ...autoEntries];\n const uniqueBySlug = new Map();\n\n for (const item of all) {\n if (uniqueBySlug.has(item.slug)) {\n continue;\n }\n uniqueBySlug.set(item.slug, item);\n }\n return [...uniqueBySlug.values()];\n}\n\nfunction toSidebarItems(entries, locale) {\n return entries\n .map((entry) => ({\n text: locale === \"zh\" ? entry.titleZh || entry.titleEn : entry.titleEn,\n link: locale === \"zh\" ? `/zh/${entry.slug}` : `/${entry.slug}`,\n }))\n .sort((a, b) => a.link.localeCompare(b.link));\n}\n\nfunction buildOverviewSidebar(entries, locale) {\n const overviewEntries = entries.filter((entry) => entry.sectionId === \"overview\");\n const slugOrder = [\"overview/home\", \"overview/architecture\"];\n const items = overviewEntries\n .sort((a, b) => {\n const ai = slugOrder.indexOf(a.slug);\n const bi = slugOrder.indexOf(b.slug);\n if (ai === -1 && bi === -1) return a.slug.localeCompare(b.slug);\n if (ai === -1) return 1;\n if (bi === -1) return -1;\n return ai - bi;\n })\n .map((entry) => ({\n text: locale === \"zh\" ? entry.titleZh || entry.titleEn : entry.titleEn,\n link: locale === \"zh\" ? `/zh/${entry.slug}` : `/${entry.slug}`,\n }));\n if (items.length === 0) {\n return [];\n }\n return [{ text: locale === \"zh\" ? \"Overview\" : \"Overview\", items }];\n}\n\nfunction buildModulesSidebar(entries, locale) {\n const modules = entries.filter((entry) => entry.sectionId === \"modules\");\n const byPrefix = new Map();\n for (const entry of modules) {\n const prefix = entry.slug.split(\"/\")[0];\n const arr = byPrefix.get(prefix) ?? [];\n arr.push(entry);\n byPrefix.set(prefix, arr);\n }\n\n const order = [\"sdks\", \"specs\", \"design\", \"server\", \"components\", \"sandboxes\", \"kubernetes\"];\n const blocks = [];\n for (const prefix of order) {\n const groupEntries = byPrefix.get(prefix);\n if (!groupEntries || groupEntries.length === 0) {\n continue;\n }\n blocks.push({\n text: moduleGroupLabels[locale][prefix],\n items: toSidebarItems(groupEntries, locale),\n });\n }\n return blocks;\n}\n\nfunction buildExamplesSidebar(entries, locale) {\n const items = toSidebarItems(entries.filter((entry) => entry.sectionId === \"examples\"), locale);\n if (items.length === 0) {\n return [];\n }\n return [{ text: locale === \"zh\" ? \"็คบไพ‹\" : \"Examples\", items }];\n}\n\nfunction buildCommunitySidebar(entries, locale) {\n const blocks = [];\n const communityEntries = entries.filter(\n (entry) => entry.sectionId === \"community\" && entry.slug.startsWith(\"community/\"),\n );\n if (communityEntries.length > 0) {\n blocks.push({\n text: communityGroupLabels[locale].community,\n items: toSidebarItems(communityEntries, locale),\n });\n }\n\n const osepReadmeEntries = entries.filter((entry) => entry.sectionId === \"community\" && entry.slug === \"oseps/readme\");\n const osepDocEntries = entries.filter(\n (entry) => entry.sectionId === \"community\" && entry.slug.startsWith(\"oseps/\") && entry.slug !== \"oseps/readme\",\n );\n const sortedOsepDocs = osepDocEntries.sort((a, b) => a.slug.localeCompare(b.slug));\n const osepItems = [...toSidebarItems(osepReadmeEntries, locale), ...toSidebarItems(sortedOsepDocs, locale)];\n if (osepItems.length > 0) {\n blocks.push({\n text: communityGroupLabels[locale].oseps,\n items: osepItems,\n });\n }\n\n return blocks;\n}\n\nfunction buildSidebarByPath(entries, locale) {\n const prefix = locale === \"zh\" ? \"/zh\" : \"\";\n const overviewSidebar = buildOverviewSidebar(entries, locale);\n const modulesSidebar = buildModulesSidebar(entries, locale);\n const examplesSidebar = buildExamplesSidebar(entries, locale);\n const communitySidebar = buildCommunitySidebar(entries, locale);\n\n const sidebar = {\n [`${prefix}/`]: overviewSidebar,\n [`${prefix}/overview/`]: overviewSidebar,\n [`${prefix}/examples/`]: examplesSidebar,\n [`${prefix}/community/`]: communitySidebar,\n [`${prefix}/oseps/`]: communitySidebar,\n };\n\n for (const modulesPrefix of [\"server\", \"components\", \"sandboxes\", \"kubernetes\", \"specs\", \"sdks\", \"design\"]) {\n sidebar[`${prefix}/${modulesPrefix}/`] = modulesSidebar;\n }\n return sidebar;\n}\n\nfunction writeGeneratedPages(entries) {\n rmIfExists(generatedRoot);\n ensureDir(path.join(generatedRoot, \"en\"));\n ensureDir(path.join(generatedRoot, \"zh\"));\n\n const rewrites = {};\n const pages = [];\n\n for (const entry of entries) {\n const enSourcePath = entry.enPath;\n const zhSourcePath = entry.zhPath || entry.enPath;\n const enGeneratedRel = `generated/en/${entry.slug}.md`;\n const zhGeneratedRel = `generated/zh/${entry.slug}.md`;\n const enGeneratedAbs = path.join(docsRoot, enGeneratedRel);\n const zhGeneratedAbs = path.join(docsRoot, zhGeneratedRel);\n ensureDir(path.dirname(enGeneratedAbs));\n ensureDir(path.dirname(zhGeneratedAbs));\n\n fs.writeFileSync(\n enGeneratedAbs,\n renderPageSource({\n locale: \"en\",\n title: entry.titleEn,\n sourceRelPath: enSourcePath,\n routeSlug: entry.slug,\n passthrough: entry.passthrough === true,\n }),\n \"utf8\",\n );\n\n fs.writeFileSync(\n zhGeneratedAbs,\n renderPageSource({\n locale: \"zh\",\n title: entry.titleZh || entry.titleEn,\n sourceRelPath: zhSourcePath,\n routeSlug: entry.slug,\n passthrough: entry.passthrough === true,\n }),\n \"utf8\",\n );\n\n rewrites[enGeneratedRel] = `${entry.slug}.md`;\n rewrites[zhGeneratedRel] = `zh/${entry.slug}.md`;\n\n pages.push({\n key: entry.key,\n slug: entry.slug,\n en: enSourcePath,\n zh: zhSourcePath,\n });\n }\n\n return { rewrites, pages };\n}\n\nexport function buildManifest() {\n const entries = buildEntries();\n const { rewrites, pages } = writeGeneratedPages(entries);\n const manifest = {\n generatedAt: new Date().toISOString(),\n pages,\n nav: {\n en: [\n { text: \"Overview\", link: \"/overview/home\" },\n { text: \"Project\", link: \"/sdks/sandbox/python/readme\" },\n { text: \"Examples\", link: \"/examples/readme\" },\n { text: \"Community\", link: \"/community/contributing\" },\n ],\n zh: [\n { text: \"Overview\", link: \"/zh/overview/home\" },\n { text: \"Project\", link: \"/zh/sdks/sandbox/python/readme\" },\n { text: \"Examples\", link: \"/zh/examples/readme\" },\n { text: \"Community\", link: \"/zh/community/contributing\" },\n ],\n },\n sidebar: {\n en: buildSidebarByPath(entries, \"en\"),\n zh: buildSidebarByPath(entries, \"zh\"),\n },\n rewrites,\n };\n\n ensureDir(path.dirname(manifestPath));\n fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\\n`, \"utf8\");\n return manifest;\n}\n\nexport function loadManifest() {\n try {\n if (!fs.existsSync(manifestPath)) {\n return buildManifest();\n }\n const data = JSON.parse(fs.readFileSync(manifestPath, \"utf8\"));\n if (!data || !data.generatedAt || !data.nav || !data.sidebar || !data.rewrites) {\n return buildManifest();\n }\n return buildManifest();\n } catch (_error) {\n return buildManifest();\n }\n}\n\nif (process.argv[1] === fileURLToPath(import.meta.url)) {\n const manifest = buildManifest();\n // Keep logging terse for CI output.\n console.log(`docs manifest generated (${manifest.pages.length} pages)`);\n}\n" }, { "path": "docs/.vitepress/theme/index.ts", "content": "import DefaultTheme from \"vitepress/theme\";\nimport \"./styles.css\";\n\nexport default DefaultTheme;\n" }, { "path": "docs/.vitepress/theme/styles.css", "content": ":root {\n --vp-c-brand-1: #2563eb;\n --vp-c-brand-2: #1d4ed8;\n --vp-c-brand-3: #1e40af;\n}\n\n.VPFeature {\n border: 1px solid var(--vp-c-divider);\n border-radius: 14px;\n}\n\n.vp-doc blockquote {\n border-left: 3px solid var(--vp-c-brand-1);\n}\n\n/* Keep README badge rows inline in VitePress docs pages */\n.vp-doc p[align=\"center\"] {\n text-align: center;\n}\n\n.vp-doc p[align=\"center\"] a {\n display: inline-flex;\n align-items: center;\n text-decoration: none;\n margin: 2px 4px;\n}\n\n.vp-doc p[align=\"center\"] a img {\n display: inline-block;\n margin: 0;\n vertical-align: middle;\n}\n\n.scenario-grid {\n display: grid;\n grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));\n gap: 14px;\n margin: 16px 0 6px;\n}\n\n.vp-doc .scenario-card {\n display: block;\n border: 1px solid var(--vp-c-divider);\n border-radius: 12px;\n padding: 14px;\n text-decoration: none;\n color: inherit;\n background: var(--vp-c-bg-soft);\n transition: border-color 0.2s ease, transform 0.2s ease;\n}\n\n.vp-doc .scenario-card:hover {\n border-color: var(--vp-c-brand-1);\n transform: translateY(-1px);\n text-decoration: none;\n}\n\n.vp-doc .scenario-card h3 {\n margin: 0 0 8px;\n font-size: 16px;\n text-decoration: none;\n}\n\n.vp-doc .scenario-card p {\n margin: 0;\n font-size: 14px;\n line-height: 1.5;\n color: var(--vp-c-text-2);\n text-decoration: none;\n}\n" }, { "path": "docs/README.md", "content": "# OpenSandbox Docs Site\n\nThis directory hosts the VitePress site for OpenSandbox.\n\n## Local development\n\n```bash\nnvm use 22\ncd docs\npnpm install\npnpm docs:dev\n```\n\n## Build\n\n```bash\nnvm use 22\ncd docs\npnpm install\npnpm docs:build\n```\n\n## Notes\n\n- Site content is generated from repository README and docs markdown files.\n- Run `pnpm docs:sync` to regenerate the manifest and routed pages.\n- Run `pnpm docs:spec` to regenerate `docs/public/api/spec-inline.js` from `specs/sandbox-lifecycle.yml`.\n" }, { "path": "docs/README_zh.md", "content": "
\n \"OpenSandbox\n\n

OpenSandbox

\n\n

\n \n \"GitHub\n \n \n \"Ask\n \n \n \"license\"\n \n \n \"PyPI\n \n \n \"npm\n \n \n \"CNCF\n \n \n \"DingTalk\"\n \n \n \"E2E\n \n

\n\n
\n
\n\nไธญๆ–‡ | [English](../README.md)\n\nOpenSandbox ๆ˜ฏไธ€ไธช้ขๅ‘ AI ๅบ”็”จๅœบๆ™ฏ่ฎพ่ฎก็š„ใ€Œ้€š็”จๆฒ™็ฎฑๅนณๅฐใ€๏ผŒไธบLLM็›ธๅ…ณ็š„่ƒฝๅŠ›๏ผˆๅ‘ฝไปคๆ‰ง่กŒใ€ๆ–‡ไปถๆ“ไฝœใ€ไปฃ็ ๆ‰ง่กŒใ€ๆต่งˆๅ™จๆ“ไฝœใ€Agent ่ฟ่กŒ็ญ‰๏ผ‰ๆไพ› **ๅคš่ฏญ่จ€ SDKใ€ๆฒ™็ฎฑๆŽฅๅฃๅ่ฎฎๅ’Œๆฒ™็ฎฑ่ฟ่กŒๆ—ถ**ใ€‚\n\nOpenSandbox ๅทฒ่ฟ›ๅ…ฅ [CNCF Landscape](https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox)ใ€‚\n\n## ๆ ธๅฟƒ็‰นๆ€ง\n\n- **ๅคš่ฏญ่จ€ SDK**๏ผšๆไพ› Pythonใ€Java/Kotlinใ€JavaScript/TypeScriptใ€C#/.NET ็ญ‰่ฏญ่จ€็š„ๅฎขๆˆท็ซฏ SDK๏ผŒGo SDK ไปๅœจ่ง„ๅˆ’ไธญใ€‚\n- **ๆฒ™็ฎฑๅ่ฎฎ**๏ผšๅฎšไน‰ไบ†ๆฒ™็ฎฑ็”Ÿๅ‘ฝๅ‘จๆœŸ็ฎก็† API ๅ’Œๆฒ™็ฎฑๆ‰ง่กŒ APIใ€‚ไฝ ๅฏไปฅ้€š่ฟ‡่ฟ™ไบ›ๆฒ™็ฎฑๅ่ฎฎๆ‰ฉๅฑ•่‡ชๅทฑ็š„ๆฒ™็ฎฑ่ฟ่กŒๆ—ถใ€‚\n- **ๆฒ™็ฎฑ่ฟ่กŒๆ—ถ**๏ผšๆฒ™็ฎฑๅ…จ็”Ÿๅ‘ฝๅ‘จๆœŸ็ฎก็†๏ผŒๆ”ฏๆŒ Docker ๅ’Œ[่‡ช็ ”้ซ˜ๆ€ง่ƒฝ Kubernetes ่ฟ่กŒๆ—ถ](../kubernetes)๏ผŒๅฎž็Žฐๆœฌๅœฐ่ฟ่กŒใ€ไผไธš็บงๅคง่ง„ๆจกๅˆ†ๅธƒๅผๆฒ™็ฎฑ่ฐƒๅบฆใ€‚\n- **ๆฒ™็ฎฑ็Žฏๅขƒ**๏ผšๅ†…็ฝฎ Commandใ€Filesystemใ€Code Interpreter ๅฎž็Žฐใ€‚ๅนถๆไพ› Coding Agent๏ผˆClaude Code ็ญ‰๏ผ‰ใ€ๆต่งˆๅ™จ่‡ชๅŠจๅŒ–๏ผˆChromeใ€Playwright๏ผ‰ๅ’ŒๆกŒ้ข็Žฏๅขƒ๏ผˆVNCใ€VS Code๏ผ‰็ญ‰็คบไพ‹ใ€‚\n- **็ฝ‘็ปœ็ญ–็•ฅ**๏ผšๆไพ›็ปŸไธ€็š„ [Ingress Gateway](../components/ingress) ๅฎž็Žฐ๏ผŒๅนถๆ”ฏๆŒๅคš็ง่ทฏ็”ฑ็ญ–็•ฅ๏ผ›ๆไพ›ๅ•ๅฎžไพ‹็บงๅˆซ็š„ๆฒ™็ฎฑ[ๅ‡บๅฃ็ฝ‘็ปœ้™ๅˆถ](../components/egress)ใ€‚\n- **ๅผบ้š”็ฆปๅฎ‰ๅ…จ**๏ผšๆ”ฏๆŒ gVisorใ€Kata Containers ๅ’Œ Firecracker ๅพฎ่™šๆ‹Ÿๆœบ็ญ‰ๅฎ‰ๅ…จๅฎนๅ™จ่ฟ่กŒๆ—ถ๏ผŒไธบๆฒ™็ฎฑๅทฅไฝœ่ดŸ่ฝฝไธŽๅฎฟไธปๆœบไน‹้—ดๆไพ›ๅขžๅผบ็š„ๅฎ‰ๅ…จ้š”็ฆปใ€‚่ฏฆ่ง [ๅฎ‰ๅ…จๅฎนๅ™จ่ฟ่กŒๆ—ถๆŒ‡ๅ—](secure-container.md)ใ€‚\n\n## ไฝฟ็”จ็คบไพ‹\n\n### ๆฒ™็ฎฑๅŸบ็ก€ๆ“ไฝœ\n\n็Žฏๅขƒ่ฆๆฑ‚๏ผš\n\n- Docker๏ผˆๆœฌๅœฐ่ฟ่กŒๅฟ…้œ€๏ผ‰\n- Python 3.10+๏ผˆๆœฌๅœฐ runtime ๅ’Œๅฟซ้€Ÿๅผ€ๅง‹๏ผ‰\n\n#### 1. ๅฎ‰่ฃ…ๅนถ้…็ฝฎ Server\n\n```bash\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker-zh\n```\n\n> ๅฆ‚ๆžœ้œ€่ฆๅผ€ๅ‘ๆˆ–ไฝฟ็”จๆบ็ ็ผ–่ฏ‘๏ผŒๅฏ้€š่ฟ‡cloneไป“ๅบ“่ฟ›่กŒๅผ€ๅ‘ใ€‚\n> \n> ```bash\n> git clone https://github.com/alibaba/OpenSandbox.git\n> cd OpenSandbox/server\n> uv sync\n> cp example.config.toml ~/.sandbox.toml # Copy configuration file\n> uv run python -m src.main # Start the service\n> ```\n\n#### 2. ๅฏๅŠจๆฒ™็ฎฑ Server\n\n```bash\nopensandbox-server\n\n# Show help\nopensandbox-server -h\n```\n\n#### 3. ๅˆ›ๅปบไปฃ็ ่งฃ้‡Šๅ™จ๏ผŒๅนถๅœจๆฒ™็ฎฑไธญๆ‰ง่กŒๅ‘ฝไปค\n\nๅฎ‰่ฃ… Code Interpreter SDK\n\n```bash\nuv pip install opensandbox-code-interpreter\n```\n\nๅˆ›ๅปบๆฒ™็ฎฑๅนถๆ‰ง่กŒๅ‘ฝไปค\n\n```python\nimport asyncio\nfrom datetime import timedelta\n\nfrom code_interpreter import CodeInterpreter, SupportedLanguage\nfrom opensandbox import Sandbox\nfrom opensandbox.models import WriteEntry\n\nasync def main() -> None:\n # 1. Create a sandbox\n sandbox = await Sandbox.create(\n \"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\",\n entrypoint= [\"/opt/opensandbox/code-interpreter.sh\"],\n env={\"PYTHON_VERSION\": \"3.11\"},\n timeout=timedelta(minutes=10),\n )\n\n async with sandbox:\n\n # 2. Execute a shell command\n execution = await sandbox.commands.run(\"echo 'Hello OpenSandbox!'\")\n print(execution.logs.stdout[0].text)\n\n # 3. Write a file\n await sandbox.files.write_files([\n WriteEntry(path=\"/tmp/hello.txt\", data=\"Hello World\", mode=644)\n ])\n\n # 4. Read a file\n content = await sandbox.files.read_file(\"/tmp/hello.txt\")\n print(f\"Content: {content}\") # Content: Hello World\n\n # 5. Create a code interpreter\n interpreter = await CodeInterpreter.create(sandbox)\n\n # 6. ๆ‰ง่กŒ Python ไปฃ็ ๏ผˆๅ•ๆฌกๆ‰ง่กŒ๏ผš็›ดๆŽฅไผ  language๏ผ‰\n result = await interpreter.codes.run(\n \"\"\"\n import sys\n print(sys.version)\n result = 2 + 2\n result\n \"\"\",\n language=SupportedLanguage.PYTHON,\n )\n\n print(result.result[0].text) # 4\n print(result.logs.stdout[0].text) # 3.11.14\n\n # 7. Cleanup the sandbox\n await sandbox.kill()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### ๆ›ดๅคš็คบไพ‹\n\nOpenSandbox ๆไพ›ไบ†ไธฐๅฏŒ็š„็คบไพ‹ๆฅๆผ”็คบไธๅŒๅœบๆ™ฏไธ‹็š„ๆฒ™็ฎฑไฝฟ็”จๆ–นๅผใ€‚ๆ‰€ๆœ‰็คบไพ‹ไปฃ็ ไฝไบŽ `examples/` ็›ฎๅฝ•ไธ‹ใ€‚\n\n#### ๐ŸŽฏ ๅŸบ็ก€็คบไพ‹\n\n- **[code-interpreter](../examples/code-interpreter/README.md)** - Code Interpreter SDK ็š„็ซฏๅˆฐ็ซฏๆฒ™็ฎฑๆต็จ‹็คบไพ‹ใ€‚\n- **[aio-sandbox](../examples/aio-sandbox/README.md)** - ไฝฟ็”จ OpenSandbox SDK ไธŽ agent-sandbox ็š„ไธ€ไฝ“ๅŒ–ๆฒ™็ฎฑ็คบไพ‹ใ€‚\n- **[agent-sandbox](../examples/agent-sandbox/README.md)** - ้€š่ฟ‡ kubernetes-sigs/agent-sandbox ๅœจ Kubernetes ไธŠ่ฟ่กŒ OpenSandboxใ€‚\n\n#### ๐Ÿค– Coding Agent ้›†ๆˆ\n\nๅœจ OpenSandbox ไธญ๏ผŒ้›†ๆˆๅ„็ฑป Coding Agent๏ผŒๅŒ…ๆ‹ฌ Claude Codeใ€Google Geminiใ€OpenAI Codexใ€Kimi CLI ็ญ‰ใ€‚\n\n- **[claude-code](../examples/claude-code/README.md)** - ๅœจ OpenSandbox ไธญ่ฟ่กŒ Claude Codeใ€‚\n- **[gemini-cli](../examples/gemini-cli/README.md)** - ๅœจ OpenSandbox ไธญ่ฟ่กŒ Google Gemini CLIใ€‚\n- **[codex-cli](../examples/codex-cli/README.md)** - ๅœจ OpenSandbox ไธญ่ฟ่กŒ OpenAI Codex CLIใ€‚\n- **[kimi-cli](../examples/kimi-cli/README.md)** - ๅœจ OpenSandbox ไธญ่ฟ่กŒ [Kimi CLI](https://github.com/MoonshotAI/kimi-cli)๏ผˆMoonshot AI๏ผ‰ใ€‚\n- **[langgraph](../examples/langgraph/README.md)** - ๅŸบไบŽ LangGraph ็Šถๆ€ๆœบ็ผ–ๆŽ’ๆฒ™็ฎฑไปปๅŠกไธŽๅ›ž้€€้‡่ฏ•ใ€‚\n- **[google-adk](../examples/google-adk/README.md)** - ไฝฟ็”จ Google ADK ้€š่ฟ‡ OpenSandbox ๅทฅๅ…ท่ฏปๅ†™ๆ–‡ไปถๅนถๆ‰ง่กŒๅ‘ฝไปคใ€‚\n- **[nullclaw](../examples/nullclaw/README.md)** - ๅœจๆฒ™็ฎฑไธญๅฏๅŠจ Nullclaw Gatewayใ€‚\n- **[openclaw](../examples/openclaw/README_zh.md)** - ๅœจๆฒ™็ฎฑไธญๅฏๅŠจ OpenClaw Gatewayใ€‚\n\n#### ๐ŸŒ ๆต่งˆๅ™จไธŽๆกŒ้ข็Žฏๅขƒ\n\n- **[chrome](../examples/chrome/README.md)** - ๅธฆ VNC ไธŽ DevTools ็š„ๆ— ๅคด Chromium๏ผŒ็”จไบŽ่‡ชๅŠจๅŒ–/่ฐƒ่ฏ•ใ€‚\n- **[playwright](../examples/playwright/README.md)** - Playwright + Chromium ๆ— ๅคดๆŠ“ๅ–ไธŽๆต‹่ฏ•็คบไพ‹ใ€‚\n- **[desktop](../examples/desktop/README.md)** - ้€š่ฟ‡ VNC ่ฎฟ้—ฎ็š„ๅฎŒๆ•ดๆกŒ้ข็Žฏๅขƒๆฒ™็ฎฑใ€‚\n- **[vscode](../examples/vscode/README.md)** - ๅœจๆฒ™็ฎฑไธญ่ฟ่กŒ code-server๏ผˆVS Code Web๏ผ‰่ฟ›่กŒ่ฟœ็จ‹ๅผ€ๅ‘ใ€‚\n\n#### ๐Ÿง  ๆœบๅ™จๅญฆไน ไธŽ่ฎญ็ปƒ\n\n- **[rl-training](../examples/rl-training/README.md)** - ๅœจๆฒ™็ฎฑไธญ่ฟ่กŒ DQN CartPole ่ฎญ็ปƒ๏ผŒ่พ“ๅ‡บ checkpoint ไธŽ่ฎญ็ปƒๆฑ‡ๆ€ปใ€‚\n\nๆ›ดๅคš่ฏฆ็ป†ไฟกๆฏ่ฏทๅ‚่€ƒ [examples](../examples/README.md) ๅ’Œๅ„็คบไพ‹็›ฎๅฝ•ไธ‹็š„ README ๆ–‡ไปถใ€‚\n\n## ้กน็›ฎ็ป“ๆž„\n\n| ็›ฎๅฝ• | ่ฏดๆ˜Ž |\n|------|---------------------------------------------------|\n| [`sdks/`](../sdks/) | ๅคš่ฏญ่จ€ SDK๏ผˆPythonใ€Java/Kotlinใ€TypeScript/JavaScriptใ€C#/.NET๏ผ‰ |\n| [`specs/`](../specs/) | OpenAPI ไธŽ็”Ÿๅ‘ฝๅ‘จๆœŸ่ง„่Œƒ |\n| [`server/`](../server/README_zh.md) | Python FastAPI ๆฒ™็ฎฑ็”Ÿๅ‘ฝๅ‘จๆœŸๆœๅŠก๏ผŒๅนถ้›†ๆˆๅคš็ง่ฟ่กŒๆ—ถๅฎž็Žฐ |\n| [`kubernetes/`](../kubernetes/README-ZH.md) | Kubernetes ้ƒจ็ฝฒไธŽ็คบไพ‹ |\n| [`components/execd/`](../components/execd/README_zh.md) | ๆฒ™็ฎฑๆ‰ง่กŒๅฎˆๆŠค่ฟ›็จ‹๏ผŒ่ดŸ่ดฃๅ‘ฝไปคๅ’Œๆ–‡ไปถๆ“ไฝœ |\n| [`components/ingress/`](../components/ingress/README.md) | ๆฒ™็ฎฑๆต้‡ๅ…ฅๅฃไปฃ็† |\n| [`components/egress/`](../components/egress/README.md) | ๆฒ™็ฎฑ็ฝ‘็ปœ Egress ่ฎฟ้—ฎๆŽงๅˆถ |\n| [`sandboxes/`](../sandboxes/) | ๆฒ™็ฎฑ่ฟ่กŒๆ—ถๅฎž็ŽฐไธŽ้•œๅƒ๏ผˆๅฆ‚ code-interpreter๏ผ‰ |\n| [`examples/`](../examples/README.md) | ้›†ๆˆ็คบไพ‹ๅ’Œไฝฟ็”จๆกˆไพ‹ |\n| [`oseps/`](../oseps/README.md) | OpenSandbox Enhancement Proposals |\n| [`docs/`](../docs/) | ๆžถๆž„ๅ’Œ่ฎพ่ฎกๆ–‡ๆกฃ |\n| [`tests/`](../tests/) | ่ทจ็ป„ไปถ็ซฏๅˆฐ็ซฏๆต‹่ฏ• |\n| [`scripts/`](../scripts/) | ๅผ€ๅ‘ๅ’Œ็ปดๆŠค่„šๆœฌ |\n\n่ฏฆ็ป†ๆžถๆž„่ฏทๅ‚้˜… [docs/architecture.md](architecture.md)ใ€‚\n\n## ๆ–‡ๆกฃ\n\n- [docs/architecture.md](architecture.md) โ€“ ๆ•ดไฝ“ๆžถๆž„ & ่ฎพ่ฎก็†ๅฟต\n- [oseps/README.md](../oseps/README.md) โ€“ OpenSandbox ๅขžๅผบๆๆกˆ (OSEPs)\n- SDK\n - Sandbox ๅŸบ็ก€ SDK๏ผˆ[Java\\Kotlin SDK](../sdks/sandbox/kotlin/README_zh.md)ใ€[Python SDK](../sdks/sandbox/python/README_zh.md)ใ€[JavaScript/TypeScript SDK](../sdks/sandbox/javascript/README_zh.md)ใ€[C#/.NET SDK](../sdks/sandbox/csharp/README_zh.md)๏ผ‰- ๅŒ…ๅซๆฒ™็ฎฑ็”Ÿๅ‘ฝๅ‘จๆœŸใ€ๅ‘ฝไปคๆ‰ง่กŒใ€ๆ–‡ไปถๆ“ไฝœ\n - Code Interpreter SDK๏ผˆ[Java\\Kotlin SDK](../sdks/code-interpreter/kotlin/README_zh.md) ใ€[Python SDK](../sdks/code-interpreter/python/README_zh.md)ใ€[JavaScript/TypeScript SDK](../sdks/code-interpreter/javascript/README_zh.md)ใ€[C#/.NET SDK](../sdks/code-interpreter/csharp/README_zh.md)๏ผ‰- ไปฃ็ ่งฃ้‡Šๅ™จ\n- [specs/README.md](../specs/README_zh.md) - ๅŒ…ๅซๆฒ™็ฎฑ็”Ÿๅ‘ฝๅ‘จๆœŸ API ๅ’Œๆฒ™็ฎฑๆ‰ง่กŒ API ็š„ OpenAPI ๅฎšไน‰\n- [server/README.md](../server/README_zh.md) - ๅŒ…ๅซๆฒ™็ฎฑ Server ็š„ๅฏๅŠจๅ’Œ้…็ฝฎ๏ผŒๆ”ฏๆŒ Docker ไธŽ Kubernetes Runtime\n\n## ่ฎธๅฏ่ฏ\n\nๆœฌ้กน็›ฎ้‡‡็”จ [Apache 2.0 License](../LICENSE) ๅผ€ๆบใ€‚\n\nไฝ ๅฏไปฅๅœจ้ตๅฎˆ่ฎธๅฏๆกๆฌพ็š„ๅ‰ๆไธ‹๏ผŒๅฐ† OpenSandbox ็”จไบŽไธชไบบๆˆ–ๅ•†ไธš้กน็›ฎใ€‚\n\n## ่ทฏ็บฟๅ›พ [2026.03]\n\n### SDK\n\n- **ๆฒ™็ฎฑๅฎขๆˆท็ซฏ่ฟžๆŽฅๆฑ ** - ๅฎขๆˆท็ซฏๆฒ™็ฎฑ่ฟžๆŽฅๆฑ ็ฎก็†๏ผŒๆไพ›้ข„้…็ฝฎ็š„ๆฒ™็ฎฑๅฎžไพ‹๏ผŒไปฅๆฏซ็ง’็บง้€Ÿๅบฆ่Žทๅ–ๆฒ™็ฎฑ็Žฏๅขƒใ€‚\n- **Go SDK** - Go ๅฎขๆˆท็ซฏ SDK๏ผŒ็”จไบŽๆฒ™็ฎฑ็”Ÿๅ‘ฝๅ‘จๆœŸ็ฎก็†ใ€ๅ‘ฝไปคๆ‰ง่กŒๅ’Œๆ–‡ไปถๆ“ไฝœใ€‚\n\n### Sandbox Runtime\n\n- **ๆŒไน…ๅŒ–ๅญ˜ๅ‚จ** - ๆฒ™็ฎฑ็š„ๆŒไน…ๅŒ–ๅญ˜ๅ‚จๆŒ‚่ฝฝ๏ผˆๅ‚่ง [Proposal 0003](../oseps/0003-volume-and-volumebinding-support.md)๏ผ‰ใ€‚\n- **ๆœฌๅœฐ่ฝป้‡็บงๆฒ™็ฎฑ** - ไธบ่ฟ่กŒๅœจ PC ไธŠ็š„ AI ๅทฅๅ…ทๆไพ›่ฝป้‡็บงๆฒ™็ฎฑใ€‚\n- **ๅฎ‰ๅ…จๅฎนๅ™จ** - ไธบๅœจๅฎนๅ™จๅ†…่ฟ่กŒ็š„ AI Agent ๆไพ›ๅฎ‰ๅ…จๆฒ™็ฎฑใ€‚\n\n### Deployment\n\n- **้ƒจ็ฝฒๆŒ‡ๅ—** - ่‡ชๆ‰˜็ฎก Kubernetes ้›†็พค็š„้ƒจ็ฝฒๆŒ‡ๅ—ใ€‚\n\n## ่”็ณปไธŽ่ฎจ่ฎบ\n\n- Issue๏ผš้€š่ฟ‡ GitHub Issues ๆไบค bugใ€ๅŠŸ่ƒฝ่ฏทๆฑ‚ๆˆ–่ฎพ่ฎก่ฎจ่ฎบ\n- ้’‰้’‰็พค๏ผšๅŠ ๅ…ฅ [OpenSandbox ๆŠ€ๆœฏไบคๆต็พค](https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=&_dt_no_comment=1&origin=11)\n\nๆฌข่ฟŽไธ€่ตทๆŠŠ OpenSandbox ๆ‰“้€ ๆˆ AI ๅœบๆ™ฏไธ‹็š„้€š็”จๆฒ™็ฎฑๅŸบ็ก€่ฎพๆ–ฝใ€‚\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=alibaba/OpenSandbox&type=date&legend=top-left)](https://www.star-history.com/#alibaba/OpenSandbox&type=date&legend=top-left)\n" }, { "path": "docs/RELEASE_NOTE_TEMPLATE.md", "content": "# [component' name] [version]\n\n## What's New\n\nSome Docs if needed \n\n### โœจ Features\n- Feature-1 (#123)\n- Feature-2 (#456)\n\n### ๐Ÿ› Bug Fixes\n- Bug-2 (#456)\n\n### โš ๏ธ Breaking Changes\n- xxx (#789)\n\n### ๐Ÿ“ฆ Misc\n- workflow update (#789)\n- deps update (#789)\n- tests update (#789)\n\n## ๐Ÿ‘ฅ Contributors\n\nThanks to these contributors โค๏ธ\n\n- @alice\n- @bob\n" }, { "path": "docs/architecture.md", "content": "# OpenSandbox Architecture\n\nOpenSandbox is a universal sandbox platform designed for AI application scenarios, providing a complete solution with multi-language SDKs, standardized sandbox protocols, and flexible runtime implementations. This document describes the overall architecture and design philosophy of OpenSandbox.\n\n## Architecture Overview\n\n![OpenSandbox Architecture](assets/architecture.svg)\n\nThe OpenSandbox architecture consists of four main layers:\n\n1. **SDKs Layer** - Client libraries for interacting with sandboxes\n2. **Specs Layer** - OpenAPI specifications defining the protocols\n3. **Runtime Layer** - Server implementations managing sandbox lifecycle\n4. **Sandbox Instances Layer** - Running sandbox containers with injected execution daemons\n\n## 1. OpenSandbox SDKs\n\nThe SDK layer provides high-level abstractions for developers to interact with sandboxes. It handles communication with both the Sandbox Lifecycle API and the Sandbox Execution API.\n\n### Core SDK Components\n\n#### 1.1 Sandbox\n\nThe `Sandbox` class is the primary entry point for managing sandbox lifecycle:\n\n- **Create**: Provision new sandbox instances from container images\n- **Manage**: Monitor sandbox state, renew expiration, retrieve endpoints\n- **Destroy**: Terminate sandbox instances when no longer needed\n\n**Key Features:**\n- Async/await support for non-blocking operations\n- Automatic state polling for provisioning progress\n- Resource quota management (CPU, memory, GPU)\n- Metadata and environment variable injection\n- TTL-based automatic expiration with renewal\n\n#### 1.2 Filesystem\n\nThe `Filesystem` component provides comprehensive file operations within sandboxes:\n\n- **CRUD Operations**: Create, read, update, and delete files and directories\n- **Bulk Operations**: Upload/download multiple files efficiently\n- **Search**: Glob-based file searching with pattern matching\n- **Permissions**: Manage file ownership, group, and mode (chmod)\n- **Metadata**: Retrieve file info including size, timestamps, permissions\n\n**Use Cases:**\n- Uploading code files and dependencies\n- Downloading execution results and artifacts\n- Managing workspace directories\n- Searching for files by pattern\n\n#### 1.3 Commands\n\nThe `Commands` component enables shell command execution within sandboxes:\n\n- **Foreground Execution**: Run commands synchronously with real-time output streaming\n- **Background Execution**: Launch long-running processes in detached mode\n- **Stream Support**: Capture stdout/stderr via Server-Sent Events (SSE)\n- **Process Control**: Interrupt running commands via context cancellation\n- **Working Directory**: Specify custom working directory for command execution\n\n**Use Cases:**\n- Running build commands (e.g., `npm install`, `pip install`)\n- Executing system utilities (e.g., `git`, `docker`)\n- Starting web servers or services\n- Running test suites\n\n#### 1.4 CodeInterpreter\n\nThe `CodeInterpreter` component provides stateful code execution across multiple programming languages:\n\n- **Multi-Language Support**: Python, Java, JavaScript, TypeScript, Go, Bash\n- **Session Management**: Maintain execution state across multiple code blocks\n- **Jupyter Integration**: Built on Jupyter kernel protocol for robust execution\n- **Result Streaming**: Real-time output via SSE with execution counts\n- **Error Handling**: Structured error responses with tracebacks\n\n**Key Features:**\n- Variable persistence across executions within same session\n- Display data in multiple MIME types (text, HTML, images)\n- Execution interruption support\n- Execution timing and performance metrics\n\n**Use Cases:**\n- Interactive coding environments (e.g., Jupyter notebooks)\n- AI code generation and execution\n- Data analysis and visualization\n- Educational coding platforms\n\n### SDK Language Support\n\nOpenSandbox provides SDKs in multiple languages:\n\n- **Python SDK** (`sdks/sandbox/python`, `sdks/code-interpreter/python`)\n- **Java/Kotlin SDK** (`sdks/sandbox/kotlin`, `sdks/code-interpreter/kotlin`)\n- **TypeScript SDK** (Roadmap)\n\nAll SDKs follow the same design patterns and provide consistent APIs across languages.\n\n## 2. OpenSandbox Specs\n\nThe Specs layer defines two core OpenAPI specifications that establish the contract between SDKs and runtime implementations.\n\n### 2.1 Sandbox Lifecycle Spec\n\n**File**: `specs/sandbox-lifecycle.yml`\n\nThe Lifecycle Spec defines the API for managing sandbox instances throughout their lifecycle.\n\n#### Core Operations\n\n| Operation | Endpoint | Description |\n|-----------|----------|-------------|\n| **Create** | `POST /sandboxes` | Create a new sandbox from a container image |\n| **List** | `GET /sandboxes` | List sandboxes with filtering and pagination |\n| **Get** | `GET /sandboxes/{id}` | Retrieve sandbox details and status |\n| **Delete** | `DELETE /sandboxes/{id}` | Terminate a sandbox |\n| **Pause** | `POST /sandboxes/{id}/pause` | Pause a running sandbox |\n| **Resume** | `POST /sandboxes/{id}/resume` | Resume a paused sandbox |\n| **Renew** | `POST /sandboxes/{id}/renew-expiration` | Extend sandbox TTL |\n| **Endpoint** | `GET /sandboxes/{id}/endpoints/{port}` | Get public URL for a port |\n\n### 2.2 Sandbox Execution Spec\n\n**File**: `specs/execd-api.yaml`\n\nThe Execution Spec defines the API for interacting with running sandbox instances. This API is implemented by the `execd` daemon injected into each sandbox.\n\n#### API Categories\n\n**Health**\n- `GET /ping` - Health check\n\n**Code Interpreting**\n- `POST /code/context` - Create execution context\n- `POST /code` - Execute code with streaming output\n- `DELETE /code` - Interrupt code execution\n\n**Command Execution**\n- `POST /command` - Execute shell command\n- `DELETE /command` - Interrupt command\n\n**Filesystem**\n- `GET /files/info` - Get file metadata\n- `DELETE /files` - Remove files\n- `POST /files/permissions` - Change permissions\n- `POST /files/mv` - Rename/move files\n- `GET /files/search` - Search files by glob pattern\n- `POST /files/replace` - Replace file content\n- `POST /files/upload` - Upload files\n- `GET /files/download` - Download files\n- `POST /directories` - Create directories\n- `DELETE /directories` - Remove directories\n\n**Metrics**\n- `GET /metrics` - Get system metrics snapshot\n- `GET /metrics/watch` - Stream metrics via SSE\n\n## 3. OpenSandbox Runtime\n\nThe Runtime layer implements the Sandbox Lifecycle Spec and manages the orchestration of sandbox containers.\n\n### 3.1 Server Architecture\n\n**Location**: `server/`\n\nThe OpenSandbox server is a FastAPI-based service providing:\n\n- **Lifecycle Management**: Create, monitor, pause, resume, and terminate sandboxes\n- **Pluggable Runtimes**: Docker (production-ready), Kubernetes (production-ready)\n- **Async Provisioning**: Background creation to reduce latency\n- **Automatic Expiration**: Configurable TTL with renewal support\n- **Access Control**: API key authentication\n- **Observability**: Unified status tracking with transition logging\n\n### 3.2 Runtime Implementations\n\n#### Docker Runtime (Ready)\n\n**Features:**\n- Direct Docker API integration\n- Two networking modes:\n - **Host Mode**: Containers share host network (single instance)\n - **Bridge Mode**: Isolated networking with HTTP routing\n- Container lifecycle management\n- Resource quota enforcement\n- Private registry authentication\n- Volume mounting for execd injection\n- Automatic cleanup on expiration\n\n**Key Responsibilities:**\n1. Pull container images (with auth support)\n2. Create containers with resource limits\n3. Inject execd binary and start script\n4. Monitor container state\n5. Handle pause/resume operations\n6. Clean up terminated containers\n\n#### Kubernetes Runtime (Ready)\n\n**Features:**\n- Built-in **[BatchSandbox](https://github.com/alibaba/OpenSandbox/tree/main/kubernetes)** runtime with sandbox pooling, high-throughput batch creation, and heterogeneous task orchestration; also compatible with **[SIG agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox)** as an alternative runtime\n- Support for different secure container runtimes (e.g., kata-containers, gVisor)\n- Helm-based deployment for controller and server, see [documentation](https://github.com/alibaba/OpenSandbox/blob/main/kubernetes/charts/opensandbox/README.md)\n\n**Planned Features:**\n- Unified network storage mounting (ossfs, NAS, custom PVC) in both pooled and non-pooled modes\n- Pause/resume support\n\n#### Custom Runtime\n\nThe pluggable architecture allows implementing custom runtimes by:\n1. Implementing the Lifecycle Spec APIs\n2. Managing sandbox provisioning and cleanup\n3. Injecting execd into sandbox instances\n4. Reporting sandbox state transitions\n\n### 3.3 Networking and Routing\n\n#### Sandbox Router\n\n**Purpose**: Provides HTTP/HTTPS load balancing to sandbox instance ports.\n\n**Features:**\n- Dynamic endpoint generation based on sandbox ID and port\n- Supports both domain-based and wildcard routing\n- Reverse proxy to sandbox container ports\n- Automatic cleanup when sandbox terminates\n\n**Endpoint Format**: `{domain}/sandboxes/{sandboxId}/port/{port}`\n\n**Use Cases:**\n- Accessing web applications running in sandboxes\n- Connecting to development servers (e.g., VS Code Server)\n- Exposing APIs and services\n- VNC and remote desktop access\n\n## 4. Sandbox Instances\n\nSandbox instances are running containers that host user workloads with an injected execution daemon.\n\n### 4.1 Container Structure\n\nEach sandbox instance consists of:\n\n1. **Base Container**: User-specified image (e.g., `ubuntu:22.04`, `python:3.11`)\n2. **execd Daemon**: Injected execution agent implementing the Execution Spec\n3. **Entrypoint Process**: User-defined main process\n\n### 4.2 execd - Execution Daemon\n\n**Location**: `components/execd/`\n\nexecd is a Go-based HTTP daemon built on the Beego framework.\n\n#### Core Responsibilities\n\n1. **Code Execution**: Manage Jupyter kernel sessions for multi-language code execution\n2. **Command Execution**: Run shell commands with output streaming\n3. **File Operations**: Provide filesystem API for remote file management\n4. **Metrics Collection**: Monitor and report CPU, memory usage\n\n#### Architecture\n\n**Technology Stack:**\n- **Language**: Go 1.24+\n- **Web Framework**: Beego\n- **Jupyter Integration**: WebSocket-based Jupyter protocol client\n- **Streaming**: Server-Sent Events (SSE)\n\n**Package Structure:**\n- `pkg/flag/` - Configuration and CLI flags\n- `pkg/web/` - HTTP layer (controllers, models, router)\n- `pkg/runtime/` - Execution dispatcher\n- `pkg/jupyter/` - Jupyter kernel client\n- `pkg/util/` - Utilities and helpers\n\n#### Jupyter Integration\n\nexecd integrates with Jupyter Server running inside the container:\n\n1. **Session Management**: Create and maintain kernel sessions\n2. **WebSocket Communication**: Real-time bidirectional communication\n3. **Message Protocol**: Jupyter message spec implementation\n4. **Stream Parsing**: Parse execution results, outputs, errors\n\n**Supported Kernels:**\n- Python (IPython)\n- Java (IJava)\n- JavaScript (IJavaScript)\n- TypeScript (ITypeScript)\n- Go (gophernotes)\n- Bash\n\n### 4.3 Injection Mechanism\n\nThe execd daemon is injected into sandbox containers during creation:\n\n**Docker Runtime Injection Process:**\n\n1. **Pull execd Image**: Retrieve the execd container image\n2. **Extract Binary**: Copy execd binary from image to temporary location\n3. **Volume Mount**: Mount execd binary and startup script into target container\n4. **Entrypoint Override**: Modify container entrypoint to start execd first\n5. **User Process Launch**: execd forks and executes the user's entrypoint\n\n**Startup Sequence:**\n\n```bash\n# Container starts with modified entrypoint\n/opt/opensandbox/start.sh\n โ†“\n# Start Jupyter Server\njupyter notebook --port=54321 --no-browser --ip=0.0.0.0\n โ†“\n# Start execd daemon\n/opt/opensandbox/execd --jupyter-host=http://127.0.0.1:54321 --port=44772\n โ†“\n# Execute user entrypoint\nexec \"${USER_ENTRYPOINT[@]}\"\n```\n\n**Benefits:**\n- Transparent to user code\n- No image modification required\n- Dynamic injection at runtime\n- Works with any base image\n\n## 5. Communication Flow\n\n### 5.1 Sandbox Creation Flow\n\n```\nUser/SDK\n โ”‚\n โ”‚ 1. POST /sandboxes (image, entrypoint, resources)\n โ–ผ\nServer (Lifecycle API)\n โ”‚\n โ”‚ 2. Pull container image\n โ”‚ 3. Inject execd binary\n โ”‚ 4. Create container with entrypoint override\n โ”‚ 5. Start container\n โ–ผ\nSandbox Instance\n โ”‚\n โ”‚ 6. Start execd daemon\n โ”‚ 7. Start Jupyter Server\n โ”‚ 8. Execute user entrypoint\n โ–ผ\nRunning (State)\n```\n\n### 5.2 Code Execution Flow\n\n```\nUser/SDK\n โ”‚\n โ”‚ 1. Create sandbox\n โ”‚ 2. Get execd endpoint\n โ–ผ\nCodeInterpreter SDK\n โ”‚\n โ”‚ 3. POST /code/context (create session)\n โ”‚ 4. POST /code (execute code)\n โ–ผ\nexecd (Execution API)\n โ”‚\n โ”‚ 5. Route to Jupyter runtime\n โ–ผ\nJupyter Runtime\n โ”‚\n โ”‚ 6. WebSocket to Jupyter Server\n โ”‚ 7. Send execute_request\n โ–ผ\nJupyter Kernel (Python/Java/etc.)\n โ”‚\n โ”‚ 8. Execute code\n โ”‚ 9. Stream output events\n โ–ผ\nexecd\n โ”‚\n โ”‚ 10. Convert to SSE events\n โ”‚ 11. Stream to client\n โ–ผ\nCodeInterpreter SDK\n โ”‚\n โ”‚ 12. Parse events\n โ”‚ 13. Return result to user\n โ–ผ\nUser/Application\n```\n\n### 5.3 File Operations Flow\n\n```\nUser/SDK\n โ”‚\n โ”‚ 1. Upload files\n โ–ผ\nFilesystem SDK\n โ”‚\n โ”‚ 2. POST /files/upload (multipart)\n โ–ผ\nexecd (Execution API)\n โ”‚\n โ”‚ 3. Write to filesystem\n โ”‚ 4. Set permissions\n โ–ผ\nSandbox Container Filesystem\n```\n\n## 6. Design Principles\n\n### 6.1 Protocol-First Design\n\n- All interactions defined by OpenAPI specifications\n- Clear contracts between components\n- Enables polyglot implementations\n- Supports custom runtime implementations\n\n### 6.2 Separation of Concerns\n\n- **SDK**: Client-side abstraction and convenience\n- **Specs**: Protocol definition and documentation\n- **Runtime**: Sandbox orchestration and lifecycle\n- **execd**: In-sandbox execution and operations\n\n### 6.3 Extensibility\n\n- Pluggable runtime implementations\n- Custom sandbox images\n- Multiple SDK languages\n- Additional Jupyter kernels\n\n### 6.4 Security\n\n- API key authentication for lifecycle operations\n- Token-based authentication for execution operations\n- Isolated sandbox environments\n- Resource quota enforcement\n- Network isolation options\n\n### 6.5 Observability\n\n- Structured state transitions\n- Real-time metrics streaming\n- Comprehensive logging\n- Health check endpoints\n\n## 7. Use Cases\n\n### 7.1 AI Code Generation and Execution\n\nAI models (like Claude, GPT-4, Gemini) generate code that needs to be executed safely:\n\n- **Isolation**: Run untrusted AI-generated code in sandboxes\n- **Multi-Language**: Support various programming languages\n- **Iteration**: Maintain state across multiple code generations\n- **Feedback**: Capture execution results and errors for AI refinement\n\n**Examples**: [claude-code](../examples/claude-code/), [gemini-cli](../examples/gemini-cli/), [codex-cli](../examples/codex-cli/)\n\n### 7.2 Interactive Coding Environments\n\nBuild web-based coding platforms and notebooks:\n\n- **Code Execution**: Run code in isolated environments\n- **File Management**: Upload/download project files\n- **Terminal Access**: Execute shell commands\n- **Collaboration**: Share sandbox instances\n\n**Examples**: [code-interpreter](../examples/code-interpreter/)\n\n### 7.3 Browser Automation and Testing\n\nAutomate web browsers for testing and scraping:\n\n- **Headless Browsers**: Chrome, Playwright\n- **Remote Debugging**: DevTools protocol\n- **VNC Access**: Visual debugging\n- **Network Isolation**: Controlled environment\n\n**Examples**: [chrome](../examples/chrome/), [playwright](../examples/playwright/)\n\n### 7.4 Remote Development Environments\n\nProvide cloud-based development workspaces:\n\n- **VS Code Server**: Full IDE in browser\n- **Desktop Environments**: VNC-based desktops\n- **Tool Pre-installation**: Language runtimes, build tools\n- **Port Forwarding**: Access development servers\n\n**Examples**: [vscode](../examples/vscode/), [desktop](../examples/desktop/)\n\n### 7.5 Continuous Integration and Testing\n\nRun build and test pipelines in isolated environments:\n\n- **Reproducible Builds**: Consistent container images\n- **Parallel Execution**: Multiple sandbox instances\n- **Artifact Collection**: Download build outputs\n- **Resource Limits**: Prevent resource exhaustion\n\n## 8. Conclusion\n\nOpenSandbox provides a complete, production-ready platform for building AI-powered applications that require safe code execution, file management, and command execution in isolated environments. The architecture is designed to be:\n\n- **Universal**: Works with any container image\n- **Extensible**: Pluggable runtimes and custom implementations\n- **Developer-Friendly**: Multi-language SDKs with consistent APIs\n- **Production-Ready**: Robust lifecycle management and observability\n- **Secure**: Isolated environments with access control\n\nThe protocol-first design ensures that all components can evolve independently while maintaining compatibility. Whether you're building AI coding assistants, interactive notebooks, or remote development environments, OpenSandbox provides the foundation you need.\n\n## 9. References\n\n- [Contributing Guide](contributing.md)\n- [Sandbox Lifecycle Spec](../specs/sandbox-lifecycle.yml)\n- [Sandbox Execution Spec](../specs/execd-api.yaml)\n- [Server Documentation](../server/README.md)\n- [execd Documentation](../components/execd/README.md)\n- [Python SDK](../sdks/sandbox/python/README.md)\n- [Java/Kotlin SDK](../sdks/sandbox/kotlin/README.md)\n- [Examples](../examples/README.md)\n" }, { "path": "docs/index.md", "content": "---\nlayout: home\n\nhero:\n name: OpenSandbox\n text: Universal Sandbox Infrastructure for AI Applications\n tagline: Securely run commands, filesystems, code interpreters, browsers, and developer tools in isolated runtime environments.\n actions:\n - theme: brand\n text: Quick Start\n link: /overview/home\n - theme: alt\n text: Explore Architecture\n link: /overview/architecture\n\nfeatures:\n - title: Sandbox Lifecycle and Runtime Management\n details: Provision, monitor, renew, and terminate sandbox instances with Docker and Kubernetes-oriented runtime capabilities.\n - title: Multi-Language SDKs and Unified APIs\n details: Build with Python, Java/Kotlin, and JavaScript SDKs on top of standardized lifecycle and execution protocols.\n - title: Powerful In-Sandbox Execution\n details: Execute shell commands, manage files, run multi-language code interpreters, expose ports, and stream logs/metrics.\n - title: Built for Real AI Workloads\n details: Supports coding agents, browser automation, remote development, AI code execution, and RL training scenarios.\n---\n\n## Typical Scenarios\n\nOpenSandbox is now listed in the [CNCF Landscape](https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox).\n\n
\n \n

Coding Agents

\n

Run Claude Code, Gemini CLI, Codex, and other agent tools in isolated sandboxes.

\n \n \n

Browser Automation

\n

Execute Chrome and Playwright workloads with controlled runtime, filesystem, and networking.

\n \n \n

Remote Development

\n

Host VS Code Web and desktop-like environments for secure cloud development workflows.

\n \n \n

AI Code Execution

\n

Run model-generated code safely, stream outputs, and iterate quickly with reproducible environments.

\n \n \n

RL Training

\n

Launch reinforcement learning tasks with managed sandbox lifecycle and resource controls.

\n \n
\n\nExplore all scenario references in [Examples](./examples/readme).\n" }, { "path": "docs/manual-cleanup-refactor-guide.md", "content": "# Manual Cleanup Refactor Guide\n\n## Background\n\nGitHub issue: `alibaba/OpenSandbox#442`\n\nIssue summary:\n\n- Support non-expiring sandboxes\n- Let callers manage cleanup explicitly\n- Keep existing TTL-based behavior for current users\n- Work across Docker and Kubernetes runtimes where supported\n\nCurrent implementation does not support this. TTL is a hard requirement in:\n\n- API request/response models\n- Docker runtime scheduling and restore logic\n- Kubernetes workload creation and renew flows\n\nThis document captures the recommended refactor direction before implementation starts.\n\n## Refactor Goal\n\nIntroduce a manual cleanup mode without adding a new top-level mode field for now.\n\nChosen semantic:\n\n- `timeout` present: sandbox uses TTL behavior\n- `timeout` omitted or `null`: sandbox uses manual cleanup behavior\n\nNon-goals for this refactor:\n\n- Do not support magic values like `timeout=0` or `timeout=-1`\n- Do not redesign the lifecycle API beyond what is required for manual cleanup\n- Do not overload `renew_expiration` to switch a sandbox from manual mode back to TTL mode\n\n## Compatibility and Rollout\n\nThis refactor is compatible through a controlled upgrade path, not through strict protocol backward compatibility.\n\nImportant compatibility fact:\n\n- Once manual cleanup is enabled in an environment, lifecycle responses may contain `expiresAt=null`\n- Lifecycle responses may also serialize other nullable fields explicitly as `null` instead of omitting them\n- Older SDKs that assume `expiresAt` is always a timestamp may fail when they call `create`, `get`, or `list`\n- Older schema-generated clients may also fail if they assume fields such as `metadata`, `status.reason`,\n `status.message`, or `status.lastTransitionAt` are always omitted or always non-null\n- Existing TTL-based callers are unaffected as long as they do not encounter manual-cleanup sandboxes\n\nRecommended rollout order:\n\n1. Upgrade all SDKs/clients that read lifecycle API responses\n2. Upgrade the server\n3. Only then start creating sandboxes with `timeout` omitted or `null`\n\nOperational rule:\n\n- Do not create manual-cleanup sandboxes in a shared environment until all readers of the lifecycle API have been upgraded\n\nThis should be called out explicitly in release notes and upgrade documentation.\n\n## Why This Approach\n\nCompared with adding `expirationMode`, using `timeout: Optional[int]` is the smallest compatible change that still maps cleanly to the feature request.\n\nAdvantages:\n\n- Smaller API and SDK surface change\n- Easier migration from the current TTL-only model\n- Preserves current behavior for existing clients that already send `timeout`\n\nTradeoffs:\n\n- Mode becomes implicit rather than explicit\n- `timeout == null` can mean either deliberate manual mode or missing input\n- Future expansion beyond `ttl/manual` may require a second API refactor\n\nFor the current scope, these tradeoffs are acceptable.\n\n## Current State\n\n### API layer\n\nTTL is currently mandatory.\n\nRelevant files:\n\n- `server/src/api/schema.py`\n- `specs/sandbox-lifecycle.yml`\n\nCurrent constraints:\n\n- `CreateSandboxRequest.timeout` is required and bounded to `60-86400`\n- `CreateSandboxResponse.expiresAt` is required\n- `Sandbox.expiresAt` is required\n- `RenewSandboxExpirationRequest.expiresAt` is required and assumes the sandbox already has TTL semantics\n\n### Docker runtime\n\nRelevant file:\n\n- `server/src/services/docker.py`\n\nCurrent behavior:\n\n- Creation always computes `expires_at = created_at + timeout`\n- Creation always schedules expiration via in-process timer\n- Existing sandboxes are restored from the expiration label on server startup\n- Sandbox read/list responses always expose `expiresAt`\n- `renew_expiration()` only supports extending TTL\n\n### Kubernetes runtime\n\nRelevant files:\n\n- `server/src/services/k8s/kubernetes_service.py`\n- `server/src/services/k8s/batchsandbox_provider.py`\n- `server/src/services/k8s/agent_sandbox_provider.py`\n\nCurrent behavior:\n\n- Creation always computes `expires_at = created_at + timeout`\n- BatchSandbox writes `spec.expireTime`\n- agent-sandbox writes `spec.shutdownTime`\n- `renew_expiration()` patches those fields\n- Sandbox read/list responses expose `expiresAt`\n\n## Target API Semantics\n\n### Create request\n\n`CreateSandboxRequest.timeout` should become optional.\n\nRules:\n\n- `timeout` omitted or `null` means manual cleanup mode\n- `timeout` present means TTL mode\n- If present, `timeout` must still satisfy `60 <= timeout <= 86400`\n- `timeout=0` and `timeout<0` remain invalid\n\nSuggested request examples:\n\nTTL mode:\n\n```json\n{\n \"image\": { \"uri\": \"python:3.11\" },\n \"timeout\": 3600,\n \"resourceLimits\": {},\n \"entrypoint\": [\"sleep\", \"infinity\"]\n}\n```\n\nManual cleanup mode:\n\n```json\n{\n \"image\": { \"uri\": \"python:3.11\" },\n \"resourceLimits\": {},\n \"entrypoint\": [\"sleep\", \"infinity\"]\n}\n```\n\n### Response models\n\n`expiresAt` should become nullable in:\n\n- `CreateSandboxResponse`\n- `Sandbox`\n\nRules:\n\n- TTL sandbox: `expiresAt` contains an RFC 3339 timestamp\n- Manual sandbox: `expiresAt` is `null`\n\n### Renew expiration API\n\nDo not use `renew_expiration` as a mode switch.\n\nRecommended behavior:\n\n- TTL sandbox: renew works as it does today\n- Manual sandbox: renew fails clearly\n\nRecommended response:\n\n- `409 Conflict` preferred\n- `400 Bad Request` acceptable if existing error handling makes that much simpler\n\nRecommended error message:\n\n- `\"Sandbox does not have automatic expiration enabled.\"`\n\n## Implementation Strategy\n\n## 1. API and schema updates\n\nFiles to update:\n\n- `server/src/api/schema.py`\n- `specs/sandbox-lifecycle.yml`\n\nRequired changes:\n\n- Make `CreateSandboxRequest.timeout` optional\n- Make `CreateSandboxResponse.expiresAt` optional\n- Make `Sandbox.expiresAt` optional\n- Update field descriptions to document manual cleanup behavior\n- Update request/response examples in the OpenAPI spec\n\nRecommended validation rule:\n\n- No custom mode field\n- Validation only enforces bounds when `timeout` is not `None`\n\n## 2. Docker runtime refactor\n\nFile to update:\n\n- `server/src/services/docker.py`\n\n### Target behavior\n\nFor manual sandboxes:\n\n- No expiration timestamp is computed\n- No expiration label is written\n- A dedicated runtime marker should be written (for example `opensandbox.io/manual-cleanup=true`)\n- No expiration timer is scheduled\n- Sandbox survives server restart without restoration warnings\n- Read/list responses return `expiresAt=None`\n\n### Concrete refactor points\n\n#### Creation context\n\nCurrent logic:\n\n- `_prepare_creation_context()` always returns a concrete `expires_at`\n\nTarget logic:\n\n- Return `expires_at: Optional[datetime]`\n- `None` when `request.timeout is None`\n\n#### Label building\n\nCurrent logic:\n\n- Expiration label is assumed to exist\n\nTarget logic:\n\n- Only write `SANDBOX_EXPIRES_AT_LABEL` when `expires_at is not None`\n- Write a dedicated manual-cleanup label/annotation when `expires_at is None`\n\n#### Provisioning\n\nCurrent logic:\n\n- `_provision_sandbox()` always schedules expiration\n\nTarget logic:\n\n- Only call `_schedule_expiration()` when `expires_at is not None`\n\n#### Sandbox reconstruction\n\nCurrent logic:\n\n- `_container_to_sandbox()` falls back to a concrete `expires_at`\n\nTarget logic:\n\n- Manual sandbox should produce `expiresAt=None`\n- Avoid fallback behavior that fabricates an expiration timestamp from `created_at`\n\n#### Restore path\n\nCurrent logic:\n\n- `_restore_existing_sandboxes()` warns when a sandbox is missing the expiration label\n\nTarget logic:\n\n- Missing expiration label should only be treated as valid when the manual-cleanup marker is present\n- Continue warning on sandboxes that have neither an expiration label nor a manual-cleanup marker\n- Only restore timers for TTL sandboxes that actually carry expiration metadata\n\n#### Renew path\n\nCurrent logic:\n\n- `renew_expiration()` assumes every sandbox has TTL enabled\n\nTarget logic:\n\n- Reject renewal if the manual-cleanup marker is present\n- Continue treating \"missing expiration metadata without manual marker\" as malformed state rather than silently converting it to manual mode\n\n## 3. Kubernetes service refactor\n\nFiles to update:\n\n- `server/src/services/k8s/kubernetes_service.py`\n- `server/src/services/k8s/workload_provider.py`\n- `server/src/services/k8s/batchsandbox_provider.py`\n- `server/src/services/k8s/agent_sandbox_provider.py`\n\n### Key risk\n\nKubernetes support depends on the underlying CRDs.\n\nOpen question:\n\n- Can BatchSandbox omit `spec.expireTime`?\n- Can agent-sandbox omit `spec.shutdownTime`?\n\nThis must be confirmed before claiming end-to-end support.\n\n### Recommended capability design\n\nAdd a provider capability check:\n\n- `supports_manual_cleanup() -> bool`\n\nPersist the chosen mode on workload metadata as well:\n\n- TTL sandbox: keep expiration field populated\n- Manual sandbox: omit expiration field and write a provider-neutral marker (label or annotation)\n\nRationale:\n\n- Docker can support manual cleanup immediately\n- Kubernetes providers may differ based on CRD semantics\n- The server should fail clearly when the selected provider cannot represent a non-expiring sandbox\n\n### Service-layer behavior\n\nIn `KubernetesSandboxService.create_sandbox()`:\n\n- Compute `expires_at: Optional[datetime]`\n- If `request.timeout is None` and provider does not support manual cleanup, fail early with a clear message\n\nSuggested message:\n\n- `\"Manual cleanup mode is not supported by the current Kubernetes workload provider.\"`\n\n### BatchSandbox provider behavior\n\nIf supported by the CRD:\n\n- Make `expires_at` optional in provider interfaces\n- Omit `spec.expireTime` when `expires_at is None`\n- `get_expiration()` should return `None` when the field is absent\n- `update_expiration()` should reject manual sandboxes instead of silently enabling TTL\n\nIf not supported by the CRD:\n\n- Return `False` from `supports_manual_cleanup()`\n- Keep current `expireTime` behavior unchanged\n\n### agent-sandbox provider behavior\n\nIf supported by the CRD:\n\n- Make `expires_at` optional in provider interfaces\n- Omit `spec.shutdownTime` when `expires_at is None`\n- `get_expiration()` should return `None` when the field is absent\n- `update_expiration()` should reject manual sandboxes\n\nIf not supported by the CRD:\n\n- Return `False` from `supports_manual_cleanup()`\n- Keep current `shutdownTime` behavior unchanged\n\n## 4. Interface changes\n\nFiles likely affected:\n\n- `server/src/services/sandbox_service.py`\n- `server/src/services/k8s/workload_provider.py`\n\nRequired updates:\n\n- Any method signature currently assuming `expires_at: datetime` should be reviewed\n- Provider creation/update/get-expiration flows should allow `Optional[datetime]` where needed\n- Abstract service docs should describe manual cleanup semantics\n\n## Error Handling Guidance\n\nRecommended failure cases:\n\n### Unsupported runtime/provider\n\nCase:\n\n- User omits `timeout`\n- Provider cannot represent non-expiring sandbox\n\nResponse:\n\n- HTTP 400\n\nMessage:\n\n- `\"Manual cleanup mode is not supported by the current runtime/provider.\"`\n\n### Renew called for manual sandbox\n\nResponse:\n\n- HTTP 409 preferred\n\nMessage:\n\n- `\"Sandbox does not have automatic expiration enabled.\"`\n\n### Invalid timeout values\n\nKeep current behavior:\n\n- Reject `timeout=0`\n- Reject negative values\n- Reject values above max bound\n\n## Compatibility Plan\n\nThis refactor should preserve backward compatibility for current users.\n\nExpected compatibility behavior:\n\n- Existing clients sending `timeout` continue to work unchanged\n- Existing responses for TTL sandboxes remain unchanged\n- New manual-cleanup behavior is opt-in via omission of `timeout`\n\nCompatibility caveat:\n\n- Any generated SDKs may need regeneration because `timeout` and `expiresAt` types change from required to optional\n- Generated SDKs should also tolerate explicit `null` values in optional lifecycle fields, not only missing fields\n- Cross-SDK request shapes do not need to be byte-for-byte identical if language constraints differ. In particular, the\n C# SDK may use an explicit `ManualCleanup` flag instead of `timeout=null` so it can keep \"unset means use default TTL\"\n distinct from \"explicitly request manual cleanup\".\n\n## Testing Plan\n\n### API/schema tests\n\nFiles likely affected:\n\n- `server/tests/test_schema.py`\n- route tests covering create/get/list/renew\n\nAdd coverage for:\n\n- Create request without `timeout`\n- Create request with valid `timeout`\n- Reject `timeout=0`\n- Create response with `expiresAt=null`\n- Sandbox model with `expiresAt=null`\n\n### Docker tests\n\nFile likely affected:\n\n- `server/tests/test_docker_service.py`\n\nAdd coverage for:\n\n- Manual sandbox creation does not schedule expiration\n- Manual sandbox creation does not write expiration label\n- Manual sandbox get/list returns `expiresAt=None`\n- Server restart restore path ignores manual sandboxes without warning\n- Renew expiration on manual sandbox fails clearly\n- TTL sandbox behavior remains unchanged\n\n### Kubernetes service tests\n\nFiles likely affected:\n\n- `server/tests/k8s/test_kubernetes_service.py`\n- `server/tests/k8s/test_batchsandbox_provider.py`\n- `server/tests/k8s/test_agent_sandbox_provider.py`\n\nAdd coverage for:\n\n- Manual mode rejected when provider capability is false\n- Manual mode omits expiration fields when provider capability is true\n- Manual mode writes the runtime marker when provider capability is true\n- `get_expiration()` returns `None` when expiration field is absent\n- Renew expiration fails for manual sandboxes\n- TTL sandbox behavior remains unchanged\n\n### Spec/SDK validation\n\nFollow-up checks:\n\n- Regenerate or validate OpenAPI docs if needed\n- Verify generated SDKs handle optional `timeout` and nullable `expiresAt`\n\n## Suggested Implementation Order\n\n1. Update schema models in `server/src/api/schema.py`\n2. Update OpenAPI spec in `specs/sandbox-lifecycle.yml`\n3. Refactor Docker runtime to support `expires_at: Optional[datetime]`\n4. Add Kubernetes provider capability plumbing\n5. Implement Kubernetes manual mode only where confirmed supported\n6. Add and update tests\n7. Regenerate SDK/spec artifacts if required by repo workflow\n\n## Open Questions Before Coding\n\nThese should be resolved early in the branch:\n\n1. Does BatchSandbox allow `spec.expireTime` to be omitted?\n2. Does agent-sandbox allow `spec.shutdownTime` to be omitted?\n3. Should renew-on-manual return `400` or `409`?\n4. Should list/get expose any explicit hint that a sandbox is manual, or is `expiresAt=null` sufficient?\n\nRecommended implementation default for questions 1 and 2 until confirmed:\n\n- Return `False` from `supports_manual_cleanup()` for both Kubernetes providers\n- Enable Kubernetes manual mode only after CRD behavior is verified by tests or upstream documentation\n\nRecommended answer for question 4:\n\n- `expiresAt=null` is sufficient for the first iteration\n\n## Summary\n\nThe smallest practical refactor is:\n\n- Make `timeout` optional\n- Treat missing `timeout` as manual cleanup mode\n- Make `expiresAt` nullable\n- Support manual mode in Docker immediately\n- Gate Kubernetes support behind provider capability and CRD validation\n- Keep `renew_expiration()` TTL-only\n\nThis preserves current behavior while creating a clear path to non-expiring sandboxes with limited API churn.\n" }, { "path": "docs/package.json", "content": "{\n \"name\": \"opensandbox-docs\",\n \"private\": true,\n \"packageManager\": \"pnpm@9.15.0\",\n \"scripts\": {\n \"docs:sync\": \"node .vitepress/scripts/docs-manifest.mjs\",\n \"docs:spec\": \"node ../scripts/spec-doc/generate-spec.js --output docs/public/api/spec-inline.js\",\n \"docs:dev\": \"pnpm docs:sync && pnpm docs:spec && vitepress dev\",\n \"docs:build\": \"pnpm docs:sync && pnpm docs:spec && vitepress build\",\n \"docs:preview\": \"vitepress preview\"\n },\n \"devDependencies\": {\n \"vitepress\": \"^1.6.4\"\n }\n}\n" }, { "path": "docs/secure-container.md", "content": "# Secure Container Runtime Guide\n\nThis guide explains how to use secure container runtimes with OpenSandbox to provide hardware-level isolation for executing untrusted AI-generated code.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Server Configuration](#server-configuration)\n- [Docker Mode](#docker-mode)\n- [Kubernetes Mode](#kubernetes-mode)\n- [User Guide](#user-guide)\n- [Administrator Guide](#administrator-guide)\n- [Troubleshooting and Best Practices](#troubleshooting-and-best-practices)\n\n---\n\n## Overview\n\n### What are Secure Container Runtimes?\n\nSecure container runtimes provide stronger isolation than the standard runc runtime used by Docker and containerd. They add additional security layers through different mechanisms:\n\n| Runtime | Isolation Mechanism | Startup Overhead | Memory Overhead | Best For |\n|---------|---------------------|------------------|-----------------|----------|\n| **runc** (default) | Process-level cgroups | ~0ms | Minimal | Trusted workloads, local development |\n| **gVisor** | User-space kernel (syscall interception) | ~10-50ms | ~50MB | General workloads with low overhead |\n| **Kata (QEMU)** | Full VM with QEMU hypervisor | ~500ms | ~20-50MB | Maximum compatibility and isolation |\n| **Kata (Firecracker)** | MicroVM with Firecracker hypervisor | ~125ms | ~5MB | High density, minimal footprint |\n| **Kata (CLH)** | Cloud Hypervisor | ~200ms | ~10-20MB | Balanced performance and isolation |\n\n### Why Use Secure Runtimes?\n\nOpenSandbox is designed to execute untrusted code generated by AI models (Claude, GPT-4, Gemini, etc.). Secure runtimes provide:\n\n1. **Container Escape Protection**: Prevents malicious code from breaking out of the container\n2. **Kernel-Level Isolation**: Each sandbox gets its own kernel context\n3. **Multi-Tenant Safety**: Different users' sandboxes are strongly isolated\n4. **Compliance**: Meets security requirements for regulated industries\n\n### Supported Runtime Types\n\nOpenSandbox supports the following secure runtime types through server-level configuration:\n\n- `\"gvisor\"` - Google gVisor with runsc\n- `\"kata\"` - Kata Containers with QEMU hypervisor (default)\n- `\"firecracker\"` - Kata Containers with Firecracker hypervisor\n- `\"\"` (empty) - Standard runc (default, no secure runtime)\n\n### Key Design Principle\n\n**Server-Level Configuration**: The secure runtime is configured once at the server level by administrators. All sandboxes on that server transparently use the configured runtime. SDK users and API callers require **no code changes**.\n\n---\n\n## Server Configuration\n\nSecure runtimes are configured through the `~/.sandbox.toml` configuration file. The server validates the configured runtime at startup and will refuse to start if the runtime is unavailable.\n\n### Configuration File\n\nEdit `~/.sandbox.toml`:\n\n```toml\n[runtime]\ntype = \"docker\" # or \"kubernetes\"\nexecd_image = \"opensandbox/execd:latest\"\n\n# Secure container runtime configuration\n# When enabled, ALL sandboxes on this server use the specified runtime\n[secure_runtime]\n# Runtime type: \"\", \"gvisor\", \"kata\", \"firecracker\"\ntype = \"\"\n\n# Docker mode: OCI runtime name (e.g., \"runsc\" for gVisor, \"kata-runtime\" for Kata)\n# Required when runtime.type = \"docker\" and type is not empty\ndocker_runtime = \"runsc\"\n\n# Kubernetes mode: RuntimeClass name (e.g., \"gvisor\", \"kata-qemu\", \"kata-fc\")\n# Required when runtime.type = \"kubernetes\" and type is not empty\nk8s_runtime_class = \"gvisor\"\n```\n\n### Configuration Examples\n\n#### Example 1: gVisor on Docker\n\n```toml\n[runtime]\ntype = \"docker\"\nexecd_image = \"opensandbox/execd:latest\"\n\n[secure_runtime]\ntype = \"gvisor\"\ndocker_runtime = \"runsc\"\nk8s_runtime_class = \"gvisor\"\n```\n\n#### Example 2: Kata Containers on Kubernetes\n\n```toml\n[runtime]\ntype = \"kubernetes\"\nexecd_image = \"opensandbox/execd:latest\"\n\n[secure_runtime]\ntype = \"kata\"\ndocker_runtime = \"kata-runtime\"\nk8s_runtime_class = \"kata-qemu\"\n```\n\n#### Example 3: Kata + Firecracker on Kubernetes\n\n```toml\n[runtime]\ntype = \"kubernetes\"\nexecd_image = \"opensandbox/execd:latest\"\n\n[secure_runtime]\ntype = \"firecracker\"\ndocker_runtime = \"\" # Not supported in Docker mode\nk8s_runtime_class = \"kata-fc\"\n```\n\n### Startup Validation\n\nWhen the server starts, it automatically validates that the configured secure runtime is available:\n\n```bash\n$ opensandbox-server\nINFO Validating secure runtime for Docker backend\nINFO Docker OCI runtime 'runsc' is available: {...}\nINFO Application startup complete.\n```\n\nIf the runtime is not available, the server will refuse to start with a clear error message:\n\n```\nERROR Configured Docker runtime 'runsc' is not available.\n Available runtimes: runc.\n Please install and configure it in /etc/docker/daemon.json.\n```\n\n---\n\n## Docker Mode\n\nDocker mode is fully supported for secure container runtimes.\n\n### Prerequisites\n\n- Docker daemon installed and running\n- Secure runtime installed on the host\n\n### gVisor Setup for Docker\n\n#### Step 1: Install gVisor runsc\n\nFor Docker mode, you only need to install the **runsc** OCI runtime:\n\n```bash\n# Ubuntu/Debian\ncurl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg\necho \"deb [signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main\" | \\\n sudo tee /etc/apt/sources.list.d/gvisor.list\nsudo apt-get update && sudo apt-get install -y runsc\n\n# Verify installation\nrunsc --version\n```\n\n> **Note**: For Docker mode, only `runsc` is required. The `containerd-shim-runsc-v1` is only needed for Kubernetes/containerd.\n>\n> **Reference**: See [gVisor Installation Guide](https://gvisor.dev/docs/user_guide/install/) for other distributions and installation methods.\n\n#### Step 2: Configure Docker daemon\n\nUse the `runsc install` command to automatically configure Docker daemon:\n\n```bash\nsudo runsc install\n```\n\nOr manually edit `/etc/docker/daemon.json`:\n\n```json\n{\n \"runtimes\": {\n \"runsc\": {\n \"path\": \"/usr/bin/runsc\",\n \"runtimeArgs\": [\n \"--platform=systrap\",\n \"--network=host\"\n ]\n }\n }\n}\n```\n\nRestart Docker:\n\n```bash\nsudo systemctl restart docker\n```\n\n> **Reference**: See [gVisor Docker Quick Start](https://gvisor.dev/docs/user_guide/quick_start/docker/) for more details.\n\n#### Step 3: Configure OpenSandbox Server\n\nEdit `~/.sandbox.toml`:\n\n```toml\n[runtime]\ntype = \"docker\"\nexecd_image = \"opensandbox/execd:latest\"\n\n[secure_runtime]\ntype = \"gvisor\"\ndocker_runtime = \"runsc\"\n```\n\n#### Step 4: Start Server and Verify\n\n```bash\nopensandbox-server\n```\n\nCreate a test sandbox:\n\n```bash\ncurl -X POST http://localhost:8080/v1/sandboxes \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"image\": {\"uri\": \"python:3.11\"},\n \"timeout\": 3600,\n \"resourceLimits\": {\"cpu\": \"500m\", \"memory\": \"512Mi\"},\n \"entrypoint\": [\"python\", \"-u\", \"-c\", \"import time\\nwhile True: print('hello from gVisor!'); time.sleep(1)\"],\n \"metadata\": {\n \"name\": \"gvisor-docker-sandbox\"\n }\n }'\n```\n\nVerify the runtime:\n\n```bash\ndocker ps --format \"{{.ID}}\\t{{.Image}}\\t{{.Names}}\"\ndocker inspect | grep -A2 Runtime\n# Expected output:\n# \"Runtime\": \"runsc\",\n```\n\n### Kata Containers Setup for Docker\n\n#### System Requirements\n\nKata Containers requires hardware virtualization support. Verify your system meets the following requirements:\n\n**Hardware Virtualization Support:**\n```bash\n# Check if CPU supports hardware virtualization (VT-x for Intel, AMD-V for AMD)\nlscpu | grep Virtualization\n# Expected output: Virtualization: VT-x (Intel) or AMD-V (AMD)\n\n# Alternatively on Intel\ngrep -E --color=auto 'vmx|svm' /proc/cpuinfo\n# Expected: vmx (Intel) or svm (AMD) flags present\n```\n\n**KVM Module:**\n```bash\n# Check if KVM module is loaded\nlsmod | grep kvm\n# Expected: kvm_intel (Intel) or kvm_amd (AMD)\n\n# If not loaded, load KVM module\nsudo modprobe kvm_intel # For Intel\n# or\nsudo modprobe kvm_amd # For AMD\n```\n\n**Kernel Requirements:**\n- Linux kernel 5.10 or later recommended\n- KVM enabled in kernel config\n\n**Docker Requirements:**\n- Docker 20.10 or later\n- `/etc/docker/daemon.json` configured for Kata runtime\n\n#### Installation\n\nDownload and install Kata Containers static binaries from GitHub releases:\n\n```bash\n# Find the latest release at https://github.com/kata-containers/kata-containers/releases\nKATA_VERSION=\"3.27.0\"\nwget https://github.com/kata-containers/kata-containers/releases/download/${KATA_VERSION}/kata-static-${KATA_VERSION}-amd64.tar.zst\n\n# Extract to root directory - Kata will be installed in /opt/kata\nzstd -d kata-static-${KATA_VERSION}-amd64.tar.zst\ntar -xvf kata-static-${KATA_VERSION}-amd64.tar -C /\n\n# Create symbolic links for PATH access\nsudo ln -sf /opt/kata/bin/kata-runtime /usr/local/bin/kata-runtime\nsudo ln -sf /opt/kata/bin/containerd-shim-kata-v2 /usr/local/bin/containerd-shim-kata-v2\n\n# Verify installation\nkata-runtime --version\n```\n\n#### Configure Docker Daemon\n\nEdit `/etc/docker/daemon.json` to register Kata as a runtime:\n\n```json\n{\n \"default-runtime\": \"runc\",\n \"runtimes\": {\n \"kata\": {\n \"runtimeType\": \"io.containerd.kata.v2\"\n }\n }\n}\n```\n\nRestart Docker to apply changes:\n\n```bash\nsudo systemctl restart docker\n\n# Verify Kata is available in Docker\ndocker info | grep -A5 Runtimes\n# Expected output should include \"io.containerd.runc.v2 kata\"\n```\n\n#### Configure OpenSandbox Server\n\nEdit `~/.sandbox.toml`:\n\n```toml\n[runtime]\ntype = \"docker\"\nexecd_image = \"opensandbox/execd:latest\"\n\n[secure_runtime]\ntype = \"kata\"\ndocker_runtime = \"kata\"\n```\n\n#### Verify Installation\n\n**Test with OpenSandbox API**\n\nCreate a sandbox and verify it's running in a VM by checking the kernel:\n\n```bash\n# Create a test sandbox\ncurl --location 'http://127.0.0.1:8080/v1/sandboxes' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"image\": {\"uri\": \"ubuntu:latest\"},\n \"timeout\": 3600,\n \"resourceLimits\": {\"cpu\": \"500m\", \"memory\": \"512Mi\"},\n \"entrypoint\": [\"/bin/bash\", \"-c\", \"while true; do uname -a; sleep 1; done\"],\n \"metadata\": {\n \"name\": \"kata-sandbox\"\n }\n }'\n```\n\nCheck the container's kernel to verify VM isolation:\n\n```bash\n# Get the container ID\ndocker ps | grep kata-sandbox\n\n# Check the kernel inside the container (should be different from host)\ndocker exec uname -a\n# Expected output: Linux 5.10.x-generic #x86_64 ... (Kata VM kernel)\n\n# Compare with host kernel\nuname -a\n# Host kernel might be different version or have different hostname\n```\n\n**Key Indicators of Kata VM:**\n- Container runs in a separate kernel with different hostname\n- Kernel version is typically `5.10.x` (Kata's guest kernel)\n- Host process list shows `qemu-system-x86_64` or similar hypervisor process\n---\n\n## Kubernetes Mode\n\nKubernetes mode supports secure runtimes through RuntimeClass resources.\n\n### Prerequisites\n\n- Kubernetes cluster with containerd runtime\n- Secure runtime installed on all nodes\n- RuntimeClass CRDs created\n\n### gVisor Setup for Kubernetes\n\n#### Step 1: Install gVisor Components on All Nodes\n\nFor Kubernetes with containerd, you need to install **two** components:\n\n1. **runsc** - the gVisor OCI runtime\n2. **containerd-shim-runsc-v1** - the containerd shim for gVisor\n\n```bash\n# On each node - Ubuntu/Debian\ncurl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg\necho \"deb [signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main\" | \\\n sudo tee /etc/apt/sources.list.d/gvisor.list\nsudo apt-get update\n\n# Install both gVisor components\nsudo apt-get install -y runsc containerd-shim-runsc-v1\n\n# Verify installation\nrunsc --version\ncontainerd-shim-runsc-v1 --version\n```\n> **Reference**: See [gVisor Installation Guide](https://gvisor.dev/docs/user_guide/containerd/configuration/) for complete installation instructions and other distributions.\n\n#### Step 2: Configure containerd\n\nEdit `/etc/containerd/config.toml`:\n\n```toml\n[plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.runsc]\n runtime_type = \"io.containerd.runsc.v1\"\n [plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.runsc.options]\n TypeUrl = \"io.containerd.runsc.v1.options\"\n ConfigPath = \"/etc/containerd/runsc.toml\"\n```\n\n```bash\nsudo tee /etc/containerd/runsc.toml > /dev/null <<'EOF'\n[runsc]\n platform = \"ptrace\"\nEOF\n```\n\nRestart containerd:\n\n```bash\nsudo systemctl restart containerd\n```\n\n#### Step 3: Create RuntimeClass CRD\n\n```yaml\n# gvisor-runtimeclass.yaml\napiVersion: node.k8s.io/v1\nkind: RuntimeClass\nmetadata:\n name: gvisor\nhandler: runsc\nscheduling:\n nodeSelector:\n kubernetes.io/arch: amd64\n```\n\n```bash\nkubectl apply -f gvisor-runtimeclass.yaml\n```\n\n#### Step 4: Configure OpenSandbox Server\n\nEdit `~/.sandbox.toml`:\n\n```toml\n[runtime]\ntype = \"kubernetes\"\nexecd_image = \"opensandbox/execd:latest\"\n\n[secure_runtime]\ntype = \"gvisor\"\nk8s_runtime_class = \"gvisor\"\n```\n\n#### Step 5: Verify Installation\n\n```bash\n# Test the RuntimeClass\nkubectl run test-gvisor --restart=Never --image=hello-world --runtime-class=gvisor\nkubectl logs test-gvisor\nkubectl delete pod test-gvisor\n```\n\n### Kata Containers Setup for Kubernetes\n\n#### Step 1: Install Kata Containers\n\nFollow the [official Kata Containers installation guide](https://github.com/kata-containers/kata-containers/blob/main/tools/packaging/kata-deploy/helm-chart/README.md).\n\nQuick installation using Helm:\n\n```bash\n# Install kata-deploy which will set up Kata Containers via DaemonSet\nhelm install kata-deploy \"oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy\" --version \"3.27.0\" --namespace kube-system --create-namespace\n\n# Wait for kata-deploy pods to be ready\nkubectl wait --for=condition=ready pod -l name=kata-deploy -n kube-system --timeout=300s\n```\n\n> **Note**: The `kata-deploy` DaemonSet will automatically configure containerd on all nodes. Manual containerd configuration is not required when using kata-deploy.\n\n#### Step 2: Verify Installation\n\nCheck that Kata Containers is installed and RuntimeClasses are created:\n\n```bash\n# Check RuntimeClasses\nkubectl get runtimeclass\n\n# Expected output:\n# NAME HANDLER AGE\n# kata kata-qemu 10m\n# kata-qemu kata-qemu 10m\n# kata-clh kata-clh 10m\n# kata-fc kata-fc 10m\n\n# Test Kata with a simple pod\nkubectl run test-kata --restart=Never --image=hello-world --runtime-class=kata-qemu\nkubectl logs test-kata\nkubectl delete pod test-kata\n```\n\n### Creating Pools for Different Runtimes (Optional)\n\nWhen using Pool CRDs for pre-warmed sandboxes, create separate pools for each runtime type:\n\n```yaml\n# gvisor-pool.yaml\napiVersion: sandbox.opensandbox.io/v1alpha1\nkind: Pool\nmetadata:\n name: gvisor-pool\n labels:\n runtime: gvisor\nspec:\n template:\n spec:\n runtimeClassName: gvisor\n containers:\n - name: sandbox-container\n image: opensandbox/code-interpreter:v1.0.2\n capacitySpec:\n bufferMax: 10\n bufferMin: 2\n poolMax: 20\n poolMin: 5\n```\n\n---\n\n## User Guide\n\nThis section is for AI application developers using OpenSandbox.\n\n### No Code Changes Required\n\n**Important**: The secure runtime is configured at the server level. Your code does not need to change.\n\nSimply create a sandbox using the OpenSandbox Lifecycle API - the server automatically applies the configured secure runtime:\n\n**Create a test sandbox:**\n\n```bash\ncurl -X POST http://localhost:8080/v1/sandboxes \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"image\": {\"uri\": \"python:3.11\"},\n \"timeout\": 3600,\n \"resourceLimits\": {\"cpu\": \"500m\", \"memory\": \"512Mi\"},\n \"entrypoint\": [\"python\", \"-u\", \"-c\", \"import time\\nwhile True: print(\\\"hello from secure sandbox!\\\"); time.sleep(1)\"],\n \"metadata\": {\n \"name\": \"my-secure-sandbox\"\n }\n }'\n```\n\n**Response:**\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"running\"\n}\n```\n\nThe sandbox will automatically use the secure runtime configured on the server (gVisor, Kata, or runc).\n\n### How It Works\n\n1. **Administrator** configures the secure runtime in `~/.sandbox.toml`\n2. **Server** validates the runtime at startup\n3. **Server** automatically injects the runtime into each sandbox:\n - Docker mode: Adds `runtime` to HostConfig\n - Kubernetes mode: Adds `runtimeClassName` to Pod spec\n4. **User** creates sandboxes via API - no runtime parameter needed\n\n### Verifying Runtime Isolation\n\nAfter creating a sandbox, verify the runtime being used:\n\n**Docker mode:**\n```bash\ndocker ps --format \"{{.ID}}\\t{{.Image}}\\t{{.Names}}\"\ndocker inspect | grep -A2 Runtime\n# Expected output for gVisor:\n# \"Runtime\": \"runsc\",\n```\n\n**Kubernetes mode:**\n```bash\nkubectl get pod -o jsonpath='{.spec.runtimeClassName}'\n# Expected output for gVisor:\n# gvisor\n```\n\n---\n\n## Administrator Guide\n\nThis section is for platform operators and SREs managing secure runtime infrastructure.\n\n### Prerequisites\n\nSecure runtimes must be installed and configured on your infrastructure **before** configuring OpenSandbox. OpenSandbox does not install runtimes automatically.\n\n### Installation Summary\n\n| Runtime | Docker | Kubernetes |\n|---------|--------|------------|\n| gVisor | Install runsc โ†’ Configure daemon.json | Install runsc โ†’ Configure containerd โ†’ Create RuntimeClass |\n| Kata (QEMU) | Install kata-runtime โ†’ Configure daemon.json | Install Kata โ†’ Configure containerd โ†’ Create RuntimeClass |\n| Kata (Firecracker) | Not supported | Install Kata โ†’ Configure containerd โ†’ Create RuntimeClass |\n\n### Configuration Validation\n\nThe server validates secure runtime configuration at startup:\n\n1. **Docker mode**: Checks if the runtime exists in Docker daemon's runtime list\n2. **Kubernetes mode**: Checks if the RuntimeClass exists in the cluster\n\nIf validation fails, the server refuses to start with a clear error message.\n\n### Security Best Practices\n\n1. **Default to gVisor**: Provides good security with acceptable performance for most workloads\n2. **Use Kata for Untrusted Code**: Maximum isolation for completely unknown code\n3. **Regular Updates**: Keep runtimes updated for security patches\n4. **Test Compatibility**: Validate your workloads with the chosen runtime before production\n5. **Monitor Resources**: Secure runtimes have higher memory overhead\n\n### Runtime Selection Guidelines\n\n| Use Case | Recommended Runtime | Reasoning |\n|----------|---------------------|-----------|\n| Development/Testing | runc (default) | Fastest startup, lowest overhead |\n| Production AI Code Execution | gVisor | Good balance of security and performance |\n| High-Security Requirements | Kata (QEMU) | Maximum isolation, full compatibility |\n| High-Density Multi-Tenant | Kata (Firecracker) | Minimal memory overhead per sandbox |\n| Untrusted Network Code | gVisor or Kata | Syscall filtering prevents network attacks |\n\n---\n\n## Troubleshooting and Best Practices\n\n### Common Issues\n\n#### 1. Runtime Not Found (Docker)\n\n**Error**: `Configured Docker runtime 'runsc' is not available.`\n\n**Solution**: Ensure the runtime is configured in `/etc/docker/daemon.json` and Docker has been restarted:\n\n```bash\nsudo systemctl restart docker\ndocker info | grep -A5 Runtimes\n```\n\n#### 2. RuntimeClass Not Found (Kubernetes)\n\n**Error**: `RuntimeClass 'gvisor' does not exist.`\n\n**Solution**: Create the RuntimeClass CRD:\n\n```bash\nkubectl get runtimeclass\nkubectl apply -f gvisor-runtimeclass.yaml\n```\n\n#### 3. Syscall Compatibility Issues\n\n**Error**: Container exits with code 1, no logs\n\n**Cause**: gVisor doesn't implement all syscalls. Some applications may not be compatible.\n\n**Solution**: Check the [gVisor compatibility guide](https://gvisor.dev/docs/user_guide/compatibility/). Try using Kata (QEMU) which has better compatibility.\n\n#### 4. Pod Stuck in ContainerCreating\n\n**Cause**: RuntimeClass handler not configured on the node.\n\n**Solution**: Verify containerd configuration:\n\n```bash\n# On the node\nsudo containerd config dump\nsudo systemctl restart containerd\n```\n\n### Compatibility Matrix\n\n| Feature | runc | gVisor | Kata (QEMU) | Kata (CLH) | Kata (FC) |\n|---------|------|--------|-------------|------------|-----------|\n| Syscall Compatibility | Full | Partial | Full | Full | Limited |\n| GPU Support | Yes | No | Yes | Yes | No |\n| IPv6 | Yes | Yes | Yes | Yes | Yes |\n| Privileged Mode | Yes | No | Yes | Yes | No |\n| Docker Volume | Yes | Yes | Yes | Yes | Yes |\n| Systemd | Yes | No | Yes | Yes | No |\n\n### Getting Help\n\n- **Documentation**: [OpenSandbox GitHub](https://github.com/alibaba/OpenSandbox)\n- **Issues**: Report bugs via [GitHub Issues](https://github.com/alibaba/OpenSandbox/issues)\n- **Design Document**: See [OSEP-0004](/oseps/0004-secure-container-runtime) for complete design details\n" }, { "path": "docs/single_host_network.md", "content": "# Single-host network in OpenSandbox\n\nDetailed routing for a single-host deployment: how execdโ€™s proxy gives every sandbox access to HTTP and WebSocket ports through one exposed host port.\n\n![Single-host sandbox routing](assets/single_host_network.png)\n\n## Single-host routing model\n- Every sandbox container starts `execd` listening on container port `44772`. `execd` bundles a lightweight reverse proxy that intercepts requests with the `/proxy/{port}` prefix and forwards them to `127.0.0.1:{port}` inside the same container.\n- The Docker runtime binds only the host side of the execd proxy port (labeled `opensandbox.io/embedding-proxy-port`). Callers use `get_endpoint(..., port=X)` to receive `{public_host}:{host_proxy_port}/proxy/{X}`, and execd transparently routes the request back to the sandbox service on port `X`.\n- Because the proxy preserves `Upgrade`, `Connection`, and other HTTP headers, HTTP, Server-Sent Events, and WebSocket traffic share the same mapped host port without additional configuration.\n- With this setup, a single host port per sandbox suffices to reach **all** container ports. You can safely run many sandboxes on one machine without worrying about overlapping host port allocations.\n- When the caller lives inside the same Docker network (e.g., another container or Kubernetes pod), use `get_endpoint(..., resolve_internal=True)` to bypass the host mapping and return the sandbox IP (e.g., `172.17.0.3:5900`) instead.\n- The diagram above shows the routing path: host traffic hits the proxy port, execd rewrites the request towards the target container port, and upstream services remain isolated within the sandbox.\n\n## Network modes\n\n### Host network mode (single-host constraints)\n- Containers share the host network stack (`network_mode=host`) so sandbox ports are directly accessible on the host.\n- Because each sandbox binds its ports on the host, this mode practically limits you to one sandbox instance per host unless you reserve dedicated ports per sandbox.\n- `get_endpoint(..., port=X)` returns `{public_host}:{X}` with no `/proxy/` prefix, so the caller needs to know the exact host port and the host must manage firewall rules for each sandbox port.\n\n### Bridge network mode (default for single-host deployments)\n- Docker places sandboxes on an isolated bridge network, preventing container ports from being reachable without explicit mapping.\n- For single-host scaling, OpenSandbox maps only execdโ€™s proxy port (`44772`) and, optionally, port `8080`. Any other container port stays private and is reached via the proxy.\n- The reverse proxy label (`opensandbox.io/embedding-proxy-port`) identifies a host port that fronts `execd`. `get_endpoint(..., port=X)` returns `{public_host}:{host_proxy_port}/proxy/{X}`, so all internal ports can share the same host binding.\n- Port `8080` may also receive a direct host binding (`opensandbox.io/http-port`), providing a conventional HTTP endpoint without the proxy path when required.\n- This bridge setup lets a single machine host many sandboxes without port conflicts, because the same host proxy port can multiplex requests for HTTP, SSE, WebSocket, VNC, etc.\n\n## Operational notes\n- If execdโ€™s proxy port (`44772`) or the optional `8080` host mapping is missing, `get_endpoint` responds with HTTP 500 and a message stating which mapping was unavailable.\n- Always keep the `/proxy/{port}` prefix (including any additional path or query string) when embedding URLs in browser-based clients or SDKs so that execd can correctly dispatch the request.\n- This proxy-based approach means additional ports never need to be published on the host, simplifying firewall management and improving security.\n" }, { "path": "docs/zh/index.md", "content": "---\nlayout: home\n\nhero:\n name: OpenSandbox\n text: ้ขๅ‘ AI ๅบ”็”จ็š„้€š็”จๆฒ™็ฎฑๅŸบ็ก€่ฎพๆ–ฝ\n tagline: ๅœจ้š”็ฆป่ฟ่กŒๆ—ถไธญๅฎ‰ๅ…จๆ‰ง่กŒๅ‘ฝไปคใ€ๆ–‡ไปถๆ“ไฝœใ€ไปฃ็ ่งฃ้‡Šๅ™จใ€ๆต่งˆๅ™จไธŽๅผ€ๅ‘ๅทฅๅ…ทใ€‚\n actions:\n - theme: brand\n text: ๅฟซ้€Ÿๅผ€ๅง‹\n link: /zh/overview/home\n - theme: alt\n text: ๆŸฅ็œ‹ๆžถๆž„\n link: /zh/overview/architecture\n\nfeatures:\n - title: ๆฒ™็ฎฑๅ…จ็”Ÿๅ‘ฝๅ‘จๆœŸไธŽ่ฟ่กŒๆ—ถ็ฎก็†\n details: ๆ”ฏๆŒๆฒ™็ฎฑๅฎžไพ‹ๅˆ›ๅปบใ€็›‘ๆŽงใ€็ปญๆœŸไธŽ้”€ๆฏ๏ผŒ่ฆ†็›– Docker ไธŽ Kubernetes ๅœบๆ™ฏใ€‚\n - title: ๅคš่ฏญ่จ€ SDK ไธŽ็ปŸไธ€ๅ่ฎฎ\n details: ๆไพ› Pythonใ€Java/Kotlinใ€JavaScript SDK๏ผŒๅนถๅŸบไบŽ็ปŸไธ€็š„็”Ÿๅ‘ฝๅ‘จๆœŸไธŽๆ‰ง่กŒๅ่ฎฎ่ฟ›่กŒๅผ€ๅ‘ใ€‚\n - title: ๅผบๅคง็š„ๆฒ™็ฎฑๅ†…ๆ‰ง่กŒ่ƒฝๅŠ›\n details: ๆ”ฏๆŒๅ‘ฝไปคๆ‰ง่กŒใ€ๆ–‡ไปถ็ณป็ปŸๆ“ไฝœใ€ๅคš่ฏญ่จ€ไปฃ็ ่งฃ้‡Šใ€็ซฏๅฃๆšด้œฒไปฅๅŠๆ—ฅๅฟ—/ๆŒ‡ๆ ‡ๆตๅผ่Žทๅ–ใ€‚\n - title: ้ขๅ‘็œŸๅฎž AI ๅทฅไฝœ่ดŸ่ฝฝ\n details: ้€‚้… Coding Agentใ€ๆต่งˆๅ™จ่‡ชๅŠจๅŒ–ใ€่ฟœ็จ‹ๅผ€ๅ‘ใ€AI ไปฃ็ ๆ‰ง่กŒไธŽๅผบๅŒ–ๅญฆไน ่ฎญ็ปƒ็ญ‰ๅœบๆ™ฏใ€‚\n---\n\n## ๅ…ธๅž‹่ฝๅœฐๅœบๆ™ฏ\n\nOpenSandbox ๅทฒ่ฟ›ๅ…ฅ [CNCF Landscape](https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox)ใ€‚\n\n
\n \n

Coding Agent

\n

ๅœจ้š”็ฆปๆฒ™็ฎฑไธญ่ฟ่กŒ Claude Codeใ€Gemini CLIใ€Codex ็ญ‰ๅทฅๅ…ท้“พใ€‚

\n \n \n

ๆต่งˆๅ™จ่‡ชๅŠจๅŒ–

\n

่ฟ่กŒ Chromeใ€Playwright ็ญ‰ๅทฅไฝœ่ดŸ่ฝฝ๏ผŒ็ป“ๅˆๅฏๆŽง่ฟ่กŒๆ—ถใ€ๆ–‡ไปถ็ณป็ปŸไธŽ็ฝ‘็ปœ็ญ–็•ฅใ€‚

\n \n \n

่ฟœ็จ‹ๅผ€ๅ‘็Žฏๅขƒ

\n

ๆไพ› VS Code Web ไธŽๆกŒ้ขๅŒ–ๅผ€ๅ‘็Žฏๅขƒ๏ผŒๆๅ‡ไบ‘็ซฏๅผ€ๅ‘็š„ๅฎ‰ๅ…จๆ€งไธŽไธ€่‡ดๆ€งใ€‚

\n \n \n

AI ไปฃ็ ๆ‰ง่กŒ

\n

ๅฎ‰ๅ…จๆ‰ง่กŒๆจกๅž‹็”Ÿๆˆไปฃ็ ๏ผŒๆตๅผ้‡‡้›†่พ“ๅ‡บๅนถๅœจๅฏๅค็Žฐ็Žฏๅขƒไธญๅฟซ้€Ÿ่ฟญไปฃใ€‚

\n \n \n

ๅผบๅŒ–ๅญฆไน ่ฎญ็ปƒ

\n

ๅœจๅฏๆŽง่ต„ๆบไธ‹่ฟ่กŒ RL ่ฎญ็ปƒไปปๅŠก๏ผŒๅนถๅˆฉ็”จๆฒ™็ฎฑ็”Ÿๅ‘ฝๅ‘จๆœŸ่ƒฝๅŠ›็ฎก็†่ฎญ็ปƒ่ฟ‡็จ‹ใ€‚

\n \n
\n\nๆ›ดๅคšๅœบๆ™ฏ่ฏทๆŸฅ็œ‹ [็คบไพ‹](./examples/readme)ใ€‚\n" }, { "path": "examples/README.md", "content": "# OpenSandbox Examples\n\nExamples for common OpenSandbox use cases. Each subdirectory contains runnable code and documentation.\n\n## Integrations / Sandboxes\n- ๐Ÿงฐ [**aio-sandbox**](aio-sandbox): All-in-one sandbox setup using OpenSandbox SDK and agent-sandbox\n- \"Kubernetes\" [**agent-sandbox**](agent-sandbox): Create a kubernetes-sigs/agent-sandbox instance and run a command\n- ๐Ÿงช [**code-interpreter**](code-interpreter): Code Interpreter SDK singleton example\n- ๐Ÿ’พ [**host-volume-mount**](host-volume-mount): Mount host directories into sandboxes (read-write, read-only, subpath)\n- โ˜๏ธ [**docker-ossfs-volume-mount**](docker-ossfs-volume-mount): Mount OSSFS volumes in Docker runtime (inline credentials, subpath, sharing)\n- ๐ŸŽฏ [**rl-training**](rl-training): Reinforcement learning training loop inside a sandbox\n- \"Claude\" [**claude-code**](claude-code): Call Claude (Anthropic) API/CLI within the sandbox\n- \"Google [**gemini-cli**](gemini-cli): Call Google Gemini within the sandbox\n- \"OpenAI\" [**codex-cli**](codex-cli): Call OpenAI/Codex-like models within the sandbox\n- \"Kimi\" [**kimi-cli**](kimi-cli): Call Kimi Code CLI (Moonshot AI) within the sandbox\n- \"LangGraph\" [**langgraph**](langgraph): LangGraph agent orchestrating sandbox lifecycle + tools\n- \"Google [**google-adk**](google-adk): Google ADK agent calling OpenSandbox tools\n- ๐Ÿฆž [**nullclaw**](nullclaw): Launch a Nullclaw Gateway inside a sandbox\n- ๐Ÿฆž [**openclaw**](openclaw): Run an OpenClaw Gateway inside a sandbox\n- ๐Ÿ–ฅ๏ธ [**desktop**](desktop): Launch VNC desktop (Xvfb + x11vnc) for VNC client connections\n- \"Playwright\" [**playwright**](playwright): Launch headless browser (Playwright + Chromium) to scrape web content\n- \"VS [**vscode**](vscode): Launch code-server (VS Code Web) to provide browser access\n- \"Google [**chrome**](chrome): Launch headless Chromium with DevTools port exposed for remote debugging\n\n## How to Run\n- Set basic environment variables (e.g., `export SANDBOX_DOMAIN=...`, `export SANDBOX_API_KEY=...`)\n- Add provider-specific variables as needed (e.g., `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `KIMI_API_KEY`, etc.; model selection is optional)\n- Navigate to the example directory and install dependencies: `pip install -r requirements.txt` (or refer to the Dockerfile in the directory)\n- Then execute: `python main.py`\n- To run in a container, build and run using the `Dockerfile` in the directory\n- Summary: First set required environment variables via `export`, then run `python main.py` in the corresponding directory, or build/run the Docker image for that directory.\n" }, { "path": "examples/agent-sandbox/README.md", "content": "# Agent-Sandbox Example\n\nThis example creates a sandbox backed by `kubernetes-sigs/agent-sandbox` and\nexecutes `echo hello world` via the OpenSandbox Python SDK.\n\n## Prerequisites\n\n- A Kubernetes cluster with the agent-sandbox controller and CRDs installed.\n- OpenSandbox server configured with Kubernetes runtime and `workload_provider = \"agent-sandbox\"`.\n- Sandbox image should include `bash` (default example uses `ubuntu:22.04`).\n\n## Start OpenSandbox server\n\n1. Install the server package and fetch the example config for agent-sandbox:\n\n```shell\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker\n```\n\n2. Update `~/.sandbox.toml` with the following sections:\n\n```toml\n[runtime]\ntype = \"kubernetes\"\nexecd_image = \"opensandbox/execd:v1.0.7\"\n\n[kubernetes]\nnamespace = \"default\"\n# kubeconfig_path = \"/absolute/path/to/kubeconfig\" # optional if running in-cluster\nworkload_provider = \"agent-sandbox\"\n\n[agent_sandbox]\nshutdown_policy = \"Delete\"\n```\n\n3. Start the server:\n\n```shell\nopensandbox-server\n```\n\n## Run the example\n\n```shell\nuv pip install opensandbox\nuv run python examples/agent-sandbox/main.py\n```\n\n## Expected output\n\n```text\ncommand output: hello world\n```\n" }, { "path": "examples/agent-sandbox/main.py", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport asyncio\nimport os\nfrom datetime import timedelta\n\nfrom opensandbox import Sandbox\nfrom opensandbox.config import ConnectionConfig\n\n\nasync def main() -> None:\n domain = os.getenv(\"SANDBOX_DOMAIN\", \"localhost:8080\")\n api_key = os.getenv(\"SANDBOX_API_KEY\")\n image = os.getenv(\"SANDBOX_IMAGE\", \"ubuntu:22.04\")\n\n config = ConnectionConfig(\n domain=domain,\n api_key=api_key,\n request_timeout=timedelta(seconds=60),\n )\n\n sandbox = await Sandbox.create(\n image,\n connection_config=config,\n timeout=timedelta(minutes=10),\n )\n\n async with sandbox:\n execution = await sandbox.commands.run(\"echo hello world\")\n stdout = execution.logs.stdout[0].text if execution.logs.stdout else \"\"\n print(f\"command output: {stdout}\")\n await sandbox.kill()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "examples/aio-sandbox/README.md", "content": "# All-in-One (AIO) Sandbox Example\n\nThis example demonstrates how to create and access an [All-in-One (AIO) Sandbox](https://github.com/agent-infra/sandbox) via OpenSandbox.\n\n## Start OpenSandbox server [local]\n\nYou can find the latest version [here](https://github.com/agent-infra/sandbox/pkgs/container/sandbox).\n\nYou can pre-pull the target image which is used in the example.\n\n### Notes (Docker runtime requirement)\n\nThe server is configured with `runtime.type = \"docker\"` by default, so it **must** be able to connect to a running Docker daemon.\n\n- **Docker Desktop**: ensure Docker Desktop is running, then verify with `docker version`.\n- **Colima (macOS)**: start it first (`colima start`) and export the socket before starting the server:\n\n```shell\nexport DOCKER_HOST=\"unix://${HOME}/.colima/default/docker.sock\"\n```\n\n\n```shell\n# pre-pull target image\ndocker pull ghcr.io/agent-infra/sandbox:latest\n```\n\nThen, start the OpenSandbox server, you can obtain stdout log from terminal.\n\n```shell\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker\nopensandbox-server\n```\n> Note: `opensandbox-server` runs in the foreground and will keep the current terminal session busy. The example code lives in this repositoryโ€”clone it and, in a new terminal window/tab, `cd` into the project root before running the AIO sandbox creation steps below.\nIf you see errors like `FileNotFoundError: [Errno 2] No such file or directory` from `docker/transport/unixconn.py`, it usually means the Docker unix socket is missing / Docker daemon is not running.\n\n## Create and Access the AIO Sandbox Instance\n\nThis example uses a fixed configuration for quick start:\n- OpenSandbox server: `http://localhost:8080`\n- Image: `ghcr.io/agent-infra/sandbox:latest`\n- AIO port: `8080`\n- Timeout: `300s`\n\nInstall dependencies with uv under project root:\n```shell\nuv pip install opensandbox agent-sandbox==0.0.18\n```\n\nRun the example (it will create a sandbox via OpenSandbox, wait until it's Running, then connect to it via agent-sandbox):\n```shell\nuv run python examples/aio-sandbox/main.py\n```\n\nSubsequently, you will instantiate an AIO sandbox, navigate to Google, capture a screenshot, and download it to your local environment.\n\n```text\nCreating AIO sandbox with image=ghcr.io/agent-infra/sandbox:latest on OpenSandbox server http://localhost:8080...\n[check] sandbox ready after 7.1s\nAIO portal endpoint: 127.0.0.1:56123\ntotal 52\ndrwxr-x--- 10 gem gem 4096 Dec 15 13:22 .\ndrwxr-xr-x 1 root root 4096 Dec 15 13:22 ..\n-rw-r--r-- 1 gem gem 220 Jan 7 2022 .bash_logout\n-rw-r--r-- 1 gem gem 27 Dec 15 13:22 .bashrc\ndrwxr-xr-x 5 gem gem 4096 Dec 15 13:22 .cache\ndrwxrwxr-x 6 gem gem 4096 Dec 15 13:22 .config\ndrwxr-xr-x 2 gem gem 4096 Dec 15 13:22 .ipython\ndrwxr-xr-x 4 gem gem 4096 Dec 15 13:22 .jupyter\ndrwxrwxr-x 4 gem gem 4096 Dec 15 13:22 .local\ndrwxr-xr-x 3 gem gem 4096 Dec 15 13:22 .npm\ndrwxrwxr-x 3 gem gem 4096 Dec 15 13:22 .npm-global\ndrwx------ 3 gem gem 4096 Dec 15 13:22 .pki\n-rw-r--r-- 1 gem gem 807 Jan 7 2022 .profile\n-rw-rw-r-- 1 gem gem 0 Dec 15 13:22 .Xauthority\nexport TERM=xterm-256color\n\nScreenshot saved to sandbox_screenshot.png\n```\n\n## More examples\n\nFor more examples of using the AIO Sandbox, refer to agents-infra/sandbox [examples](https://github.com/agent-infra/sandbox/tree/main/examples).\n\n## References\n- [AIO Sandbox](https://github.com/agent-infra/sandbox/tree/main)\n- [AIO Sandbox Python SDK](https://github.com/agent-infra/sandbox/tree/main/sdk/python)\n" }, { "path": "examples/aio-sandbox/main.py", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"\nCreate an AIO sandbox via OpenSandbox SDK, then connect to it with agent-sandbox SDK.\n\nThis example is intentionally hard-coded for simplicity:\n- OpenSandbox server: http://localhost:8080\n- Image: ghcr.io/agent-infra/sandbox:latest\n- AIO port: 8080\n- Timeout: 300s\n\"\"\"\n\nimport time\nfrom datetime import timedelta\n\nimport requests\nfrom agent_sandbox import Sandbox as AioSandboxClient\nfrom opensandbox import SandboxSync\nfrom opensandbox.config import ConnectionConfigSync\n\n\ndef check_aio_process(sbx: SandboxSync) -> bool:\n \"\"\"\n Health check: poll aio process at /v1/shell/sessions until it returns 200.\n\n Returns:\n True when ready\n False on timeout or any exception\n \"\"\"\n try:\n endpoint = sbx.get_endpoint(8080)\n start = time.perf_counter()\n url = f\"http://{endpoint.endpoint}/v1/shell/sessions\"\n for _ in range(150): # max for ~30s\n try:\n resp = requests.get(url, timeout=1)\n if resp.status_code == 200:\n elapsed = time.perf_counter() - start\n print(f\"[check] sandbox ready after {elapsed:.1f}s\")\n return True\n except Exception as exc:\n # print(f\"[check] aio sandbox check health failed: {exc}\")\n pass\n time.sleep(0.2)\n return False\n except Exception as exc:\n print(f\"[check] failed: {exc}\")\n return False\n\n\ndef main() -> None:\n server = \"http://localhost:8080\"\n image = \"ghcr.io/agent-infra/sandbox:latest\"\n timeout_seconds = 300\n\n print(f\"Creating AIO sandbox with image={image} on OpenSandbox server {server}...\")\n sandbox = SandboxSync.create(\n image=image,\n timeout=timedelta(seconds=timeout_seconds),\n metadata={\"example\": \"aio-sandbox\"},\n entrypoint=[\"/opt/gem/run.sh\"],\n connection_config=ConnectionConfigSync(domain=server),\n health_check=check_aio_process,\n )\n\n with sandbox:\n endpoint = sandbox.get_endpoint(8080)\n print(f\"AIO portal endpoint: {endpoint.endpoint}\")\n\n client = AioSandboxClient(base_url=f\"http://{endpoint.endpoint}\")\n home_dir = client.sandbox.get_context().home_dir\n\n result = client.shell.exec_command(command=\"ls -la\", timeout=10)\n print(result.data.output)\n\n content = client.file.read_file(file=f\"{home_dir}/.bashrc\")\n print(content.data.content)\n\n screenshot_path = \"sandbox_screenshot.png\"\n with open(screenshot_path, \"wb\") as f:\n for chunk in client.browser.screenshot():\n f.write(chunk)\n print(f\"Screenshot saved to {screenshot_path}\")\n\n # kill sandbox finally\n sandbox.kill()\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "examples/chrome/Dockerfile", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nFROM golang:1.25.4 AS builder\n\nWORKDIR /build\n\nCOPY go.mod go.sum ./\n\nRUN go mod download\n\nCOPY . .\n\nRUN CGO_ENABLED=0 go build -o /build/entrypoint main.go\n\n#----------------------\n# Use a base image with a minimal set of packages.\nFROM debian:13-slim\n\n#----------------------\n# Install prerequisites, chromium, VNC, and X11 utilities.\nRUN set -eux; \\\n apt-get update; \\\n apt-get install -y --no-install-recommends \\\n ca-certificates \\\n wget \\\n xdg-utils \\\n chromium \\\n tigervnc-standalone-server \\\n x11-utils; \\\n rm -rf /var/lib/apt/lists/*\n\n# Create a non-root user to run Chrome.\nRUN groupadd -r chrome && useradd -r -g chrome -G audio,video chrome \\\n && mkdir -p /home/chrome/Downloads && chown -R chrome:chrome /home/chrome\n\n# Precreate X11 stuff\nRUN mkdir -p /tmp/.X11-unix\nRUN chmod 1777 /tmp/.X11-unix\n\nCOPY --chmod=a+rx chrome.sh /chrome.sh\nCOPY --from=builder --chmod=a+rx /build/entrypoint /entrypoint\n\nWORKDIR /home/chrome\n\nUSER chrome\n\n\nENTRYPOINT [ \"/entrypoint\" ]\n" }, { "path": "examples/chrome/README.md", "content": "# Chrome Browser in OpenSandbox\n\nThis example runs Chrome Browser with OpenSandbox runtime.\n\nThe image starts a VNC server (`Xtigervnc :1`) and launches Chromium with remote debugging enabled on port `9222`.\n\n## Getting Chrome image\n\nYou can build the image from source or pull it from Docker Hub.\n\n### Build from source\n\n```shell\ndocker build -t opensandbox/chrome .\n```\n\n### Pull an existing image\n\n```shell\ndocker pull opensandbox/chrome:latest\n\n# use acr from china\n# docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/chrome:latest\n```\n\n## Start OpenSandbox server\n\nStart the OpenSandbox server and tail stdout from the terminal:\n\n```shell\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker\nopensandbox-server\n```\n\n## Create and access a Chrome sandbox\n\nBuild/pull the image above, then create a sandbox with image `opensandbox/chrome:latest` and an entrypoint that keeps it\nalive (e.g., `[\"/bin/sh\", \"-c\", \"sleep infinity\"]`), or reuse `tail -f /dev/null`. Make sure the runtime exposes ports\n`5901` and `9222` for VNC/DevTools.\n\n```shell\nuv pip install opensandbox\nuv run python examples/chrome/main.py\n```\n\nThen fetch endpoints for 5901/9222 to connect with a VNC client or DevTools, like:\n\n```text\nexecd daemon running with endpoint='127.0.0.1:48379/proxy/44772'\nVNC running with endpoint='127.0.0.1:48379/proxy/5901'\nDevTools running with endpoint='127.0.0.1:48379/proxy/9222'/json\n```\n\n```text\n[ {\n \"description\": \"\",\n \"devtoolsFrontendUrl\": \"https://chrome-devtools-frontend.appspot.com/serve_rev/@71a0dbd6672e2ccb6d1008376cbb7acd315cb8d6/inspector.html?ws=127.0.0.1:52302/devtools/page/2215AF60AC345E4BA6D822389CFC743B\",\n \"faviconUrl\": \"https://www.gstatic.com/images/branding/searchlogo/ico/favicon.ico\",\n \"id\": \"2215AF60AC345E4BA6D822389CFC743B\",\n \"title\": \"Google\",\n \"type\": \"page\",\n \"url\": \"https://www.google.com.hk/\",\n \"webSocketDebuggerUrl\": \"ws://127.0.0.1:52302/devtools/page/2215AF60AC345E4BA6D822389CFC743B\"\n} ]\n```\n\nOr you can use it by MCP client, more information please refer\nto: [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp).\n\n## Reference\n\n- [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp)\n" }, { "path": "examples/chrome/build.sh", "content": "#!/bin/bash\n# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nset -ex\n\nTAG=${TAG:-latest}\n\ndocker buildx rm chrome-builder || true\n\ndocker buildx create --use --name chrome-builder\n\ndocker buildx inspect --bootstrap\n\ndocker buildx ls\n\ndocker buildx build \\\n -t opensandbox/chrome:${TAG} \\\n -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/chrome:${TAG} \\\n --platform linux/amd64,linux/arm64 \\\n --push \\\n .\n" }, { "path": "examples/chrome/chrome.sh", "content": "#!/bin/bash\n\n# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nset -euo pipefail\n\n# There are a lot of interesting flags we could use here: https://github.com/microsoft/playwright/blob/20023ab33a1dc04db2d5a3f753760eef33339e73/packages/playwright-core/src/server/chromium/chromiumSwitches.ts#L47\nflags=()\n\nflags+=(--no-sandbox) # We can't use sandbox in a container\n\nflags+=(--disable-gpu) # We don't (normally) have a GPU\nflags+=(--disable-dev-shm-usage) # We don't (normally) have a shared memory filesystem\n\nflags+=(--no-default-browser-check) # Avoids hanging with a \"set chrome as default browser\" dialog\nflags+=(--no-first-run) # Avoids hanging with a \"set chrome as default browser\" dialog\n\nflags+=(--start-maximized) # We're the only thing running, use the whole screen\n\nflags+=(--disable-field-trial-config) # Keeps things consistent and a little faster (?)\n\nflags+=(--remote-debugging-port=9222) # Enable remote debugging\nflags+=(--user-data-dir=/tmp/chrome-data) # DevTools remote debugging requires a non-default data directory. Specify this using --user-data-dir.\n\n# Launch Chrome\nexec chromium \"${flags[@]}\" \"https://www.google.com\"\n" }, { "path": "examples/chrome/go.mod", "content": "module github.com/alibaba/opensandbox/chrome-box\n\ngo 1.22\n" }, { "path": "examples/chrome/go.sum", "content": "" }, { "path": "examples/chrome/main.go", "content": "// Copyright 2025 Alibaba Group Holding Ltd.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage main\n\nimport (\n\t\"bytes\"\n\t\"context\"\n\t\"fmt\"\n\t\"io\"\n\t\"log\"\n\t\"net/http\"\n\t\"os\"\n\t\"os/exec\"\n\t\"strings\"\n\t\"time\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tif err := run(ctx); err != nil {\n\t\tfmt.Fprintf(os.Stderr, \"Error: %v\\n\", err)\n\t\tos.Exit(1)\n\t}\n}\n\nfunc run(ctx context.Context) error {\n\n\tctx, cancel := context.WithCancel(ctx)\n\tdefer cancel()\n\n\tvnc := &VNCServer{}\n\n\terrs := make(chan error, 10)\n\n\tgo func() {\n\t\tif err := vnc.Run(ctx); err != nil {\n\t\t\tlog.Println(err, \"VNC server exited with error\")\n\t\t\terrs <- fmt.Errorf(\"VNC server exited with error: %w\", err)\n\t\t\tcancel()\n\t\t}\n\t}()\n\n\tif err := vnc.WaitForReady(ctx); err != nil {\n\t\treturn fmt.Errorf(\"failed to wait for VNC server: %w\", err)\n\t}\n\n\tchrome := &Chrome{}\n\tgo func() {\n\t\tif err := chrome.Run(ctx); err != nil {\n\t\t\tlog.Println(err, \"Chrome exited with error\")\n\t\t\terrs <- fmt.Errorf(\"Chrome exited with error: %w\", err)\n\t\t\tcancel()\n\t\t}\n\t}()\n\n\tif err := chrome.WaitForReady(ctx); err != nil {\n\t\treturn fmt.Errorf(\"failed to wait for Chrome: %w\", err)\n\t}\n\tlog.Println(\"Chrome and VNC server are running\")\n\n\t<-ctx.Done()\n\terrs <- ctx.Err()\n\n\t// Return the first error (or nil))\n\treturn <-errs\n}\n\ntype Chrome struct {\n}\n\nfunc (c *Chrome) Run(ctx context.Context) error {\n\tcmd := exec.CommandContext(ctx, \"/chrome.sh\")\n\tcmd.Stdout = os.Stdout\n\tcmd.Stderr = os.Stderr\n\n\tvar env []string\n\tfor _, e := range os.Environ() {\n\t\tif strings.HasPrefix(e, \"DISPLAY=\") {\n\t\t\tcontinue\n\t\t}\n\t\tenv = append(env, e)\n\t}\n\tenv = append(env, \"DISPLAY=:1\")\n\tcmd.Env = env\n\n\treturn cmd.Run()\n}\n\nfunc (c *Chrome) WaitForReady(ctx context.Context) error {\n\tu := \"http://localhost:9222/json/version\"\n\n\thttpClient := &http.Client{}\n\thttpClient.Timeout = 200 * time.Millisecond\n\n\tfor {\n\t\tif ctx.Err() != nil {\n\t\t\treturn ctx.Err()\n\t\t}\n\n\t\treq, err := http.NewRequestWithContext(ctx, \"GET\", u, nil)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create HTTP request: %w\", err)\n\t\t}\n\n\t\t// Send the HTTP request\n\t\tresponse, err := httpClient.Do(req)\n\t\tif err != nil {\n\t\t\tlog.Println(\"Waiting for Chrome to be ready\", \"url\", u, \"info\", err)\n\t\t\ttime.Sleep(100 * time.Millisecond)\n\t\t\tcontinue\n\t\t}\n\t\tdefer response.Body.Close()\n\n\t\t// Check for HTTP 200 OK\n\t\tif response.StatusCode != http.StatusOK {\n\t\t\tlog.Println(\"Waiting for Chrome to be ready\", \"url\", u, \"status\", response.Status)\n\t\t\ttime.Sleep(100 * time.Millisecond)\n\t\t\tcontinue\n\t\t}\n\n\t\tb, err := io.ReadAll(response.Body)\n\t\tif err != nil {\n\t\t\tlog.Println(\"Waiting for Chrome to be ready\", \"url\", u, \"info\", err)\n\t\t\ttime.Sleep(100 * time.Millisecond)\n\t\t\tcontinue\n\t\t}\n\n\t\tlog.Println(\"Chrome is ready\", \"url\", u, \"response\", string(b))\n\t\tbreak\n\t}\n\treturn nil\n}\n\ntype VNCServer struct {\n}\n\nfunc (v *VNCServer) Run(ctx context.Context) error {\n\tcmd := exec.CommandContext(ctx, \"Xtigervnc\", \":1\", \"-geometry\", \"1280x1024\")\n\tcmd.Stdout = os.Stdout\n\tcmd.Stderr = os.Stderr\n\n\tlog.Println(\"Starting VNC server\", \"command\", cmd.String())\n\tif err := cmd.Start(); err != nil {\n\t\treturn fmt.Errorf(\"failed to start VNC server: %w\", err)\n\t}\n\n\tgo func() {\n\t\t<-ctx.Done()\n\t\tif err := cmd.Process.Kill(); err != nil {\n\t\t\tlog.Println(err, \"failed to kill VNC server\")\n\t\t}\n\t}()\n\n\tif err := cmd.Wait(); err != nil {\n\t\treturn fmt.Errorf(\"VNC server exited with error: %w\", err)\n\t}\n\n\treturn nil\n}\n\nfunc (v *VNCServer) WaitForReady(ctx context.Context) error {\n\tfor {\n\t\tif ctx.Err() != nil {\n\t\t\treturn ctx.Err()\n\t\t}\n\n\t\tcmd := exec.CommandContext(ctx, \"xdpyinfo\", \"-display\", \":1\")\n\t\tvar stdout bytes.Buffer\n\t\tcmd.Stdout = &stdout\n\t\tvar stderr bytes.Buffer\n\t\tcmd.Stderr = &stderr\n\t\tif err := cmd.Run(); err != nil {\n\t\t\tlog.Println(\"Waiting for VNC server to be ready\", \"info\", err)\n\t\t\ttime.Sleep(100 * time.Millisecond)\n\t\t\tcontinue\n\t\t}\n\n\t\tlog.Println(\"VNC is ready\")\n\t\tbreak\n\t}\n\treturn nil\n}\n" }, { "path": "examples/chrome/main.py", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport asyncio\nfrom datetime import timedelta\n\nfrom opensandbox.sandbox import Sandbox\nfrom opensandbox.config import ConnectionConfig\nfrom opensandbox.exceptions import SandboxException\n\nasync def main():\n try:\n sandbox = await Sandbox.create(\n image=\"opensandbox/chrome:latest\",\n timeout=timedelta(minutes=5),\n entrypoint=[\"/entrypoint\"],\n metadata={\"examples.opensandbox.io\": \"chrome\"},\n connection_config=ConnectionConfig(\n domain=\"localhost:8080\"\n )\n )\n\n # Got execd process endpoint\n execd = await sandbox.get_endpoint(44772)\n print(f\"execd daemon running with {execd.endpoint}\")\n\n vnc = await sandbox.get_endpoint(5901)\n print(f\"VNC running with {vnc.endpoint}\")\n\n devtools = await sandbox.get_endpoint(9222)\n print(f\"DevTools running with {devtools.endpoint}/json\")\n\n except SandboxException as e:\n # Handle Sandbox specific exceptions\n print(f\"Sandbox Error: [{e.error.code}] {e.error.message}\")\n except Exception as e:\n print(f\"Error: {e}\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "examples/claude-code/README.md", "content": "# Claude Code Example\n\nAccess Claude via the `claude-cli` npm package in OpenSandbox.\n\n## Start OpenSandbox server [local]\n\nPre-pull the code-interpreter image (includes Node.js):\n\n```shell\ndocker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\n\n# use docker hub\n# docker pull opensandbox/code-interpreter:v1.0.2\n```\n\nThen start the local OpenSandbox server, stdout logs will be visible in the terminal:\n\n```shell\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker\nopensandbox-server\n```\n\n## Create and Access the Claude Sandbox\n\n```shell\n# Install OpenSandbox package\nuv pip install opensandbox\n\n# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY / ANTHROPIC_AUTH_TOKEN)\nuv run python examples/claude-code/main.py\n```\n\nThe script installs the Claude CLI (`npm i -g @anthropic-ai/claude-code@latest`) at runtime (Node.js is already in the code-interpreter image), then sends a simple request `claude \"Compute 1+1=?.\"`. Auth is passed via `ANTHROPIC_AUTH_TOKEN`, and you can override endpoint/model with `ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL`.\n\n![Claude Code screenshot](./screenshot.jpg)\n\n## Environment Variables\n\n- `SANDBOX_DOMAIN`: Sandbox service address (default: `localhost:8080`)\n- `SANDBOX_API_KEY`: API key if your server requires authentication (optional for local)\n- `SANDBOX_IMAGE`: Sandbox image to use (default: `sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2`)\n- `ANTHROPIC_AUTH_TOKEN`: Your Anthropic auth token (required)\n- `ANTHROPIC_BASE_URL`: Anthropic API endpoint (optional; e.g., self-hosted proxy)\n- `ANTHROPIC_MODEL`: Model name (default: `claude_sonnet4`)\n\n## References\n- [claude-code](https://www.npmjs.com/package/claude-code) - NPM package for Claude Code CLI\n" }, { "path": "examples/claude-code/main.py", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport asyncio\nimport os\nfrom datetime import timedelta\n\nfrom opensandbox import Sandbox\nfrom opensandbox.config import ConnectionConfig\n\n\ndef _required_env(name: str) -> str:\n value = os.getenv(name)\n if not value:\n raise RuntimeError(f\"{name} is required\")\n return value\n\n\nasync def _print_execution_logs(execution) -> None:\n for msg in execution.logs.stdout:\n print(f\"[stdout] {msg.text}\")\n for msg in execution.logs.stderr:\n print(f\"[stderr] {msg.text}\")\n if execution.error:\n print(f\"[error] {execution.error.name}: {execution.error.value}\")\n\n\nasync def main() -> None:\n domain = os.getenv(\"SANDBOX_DOMAIN\", \"localhost:8080\")\n api_key = os.getenv(\"SANDBOX_API_KEY\")\n claude_auth_token = _required_env(\"ANTHROPIC_AUTH_TOKEN\")\n claude_base_url = os.getenv(\"ANTHROPIC_BASE_URL\")\n claude_model_name = os.getenv(\"ANTHROPIC_MODEL\", \"claude_sonnet4\")\n image = os.getenv(\n \"SANDBOX_IMAGE\",\n \"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\",\n )\n\n config = ConnectionConfig(\n domain=domain,\n api_key=api_key,\n request_timeout=timedelta(seconds=60),\n )\n\n # Inject Claude settings into container environment for CLI access\n env = {\n \"ANTHROPIC_AUTH_TOKEN\": claude_auth_token,\n \"ANTHROPIC_BASE_URL\": claude_base_url,\n \"ANTHROPIC_MODEL\": claude_model_name,\n \"IS_SANDBOX\": \"1\",\n }\n # Drop None values to avoid overriding defaults inside CLI\n env = {k: v for k, v in env.items() if v is not None}\n\n sandbox = await Sandbox.create(\n image,\n connection_config=config,\n env=env,\n )\n\n async with sandbox:\n # Install Claude CLI (Node.js is already in the code-interpreter image)\n install_exec = await sandbox.commands.run(\n \"npm i -g @anthropic-ai/claude-code@latest\"\n )\n await _print_execution_logs(install_exec)\n\n # Use Claude CLI to send a message\n run_exec = await sandbox.commands.run(\n 'claude \"Compute 1+1=?.\"'\n )\n await _print_execution_logs(run_exec)\n\n await sandbox.kill()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "examples/code-interpreter/README.md", "content": "# Code Interpreter Sandbox\n\nComplete demonstration of running Python code using the Code Interpreter SDK.\n\n## Getting Code Interpreter image\n\nPull the prebuilt image from a registry:\n\n```shell\ndocker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\n\n# use docker hub\n# docker pull opensandbox/code-interpreter:v1.0.2\n```\n\n## Start OpenSandbox server [local]\n\nStart the local OpenSandbox server:\n\n```shell\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker\nopensandbox-server\n```\n\n## Create and access the Code Interpreter Sandbox\n\n```shell\n# Install OpenSandbox packages\nuv pip install opensandbox opensandbox-code-interpreter\n\n# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY)\nuv run python examples/code-interpreter/main.py\n```\n\nThe script creates a Sandbox + CodeInterpreter, runs a Python code snippet and prints stdout/result, then terminates the remote instance.\n\n## Environment variables\n\n- `SANDBOX_DOMAIN`: Sandbox service address (default: `localhost:8080`)\n- `SANDBOX_API_KEY`: API key if your server requires authentication\n- `SANDBOX_IMAGE`: Sandbox image to use (default: `sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2`)\n\n## Example output\n\n```text\n=== Python example ===\n[Python stdout] Hello from Python!\n\n[Python result] {'py': '3.14.2', 'sum': 4}\n\n=== Java example ===\n[Java stdout] Hello from Java!\n\n[Java stdout] 2 + 3 = 5\n\n[Java result] 5\n\n=== Go example ===\n[Go stdout] Hello from Go!\n3 + 4 = 7\n\n\n=== TypeScript example ===\n[TypeScript stdout] Hello from TypeScript!\n\n[TypeScript stdout] sum = 6\n```\n\n# Code Interpreter Sandbox from pool\n\n## Start OpenSandbox server [k8s]\n\nInstall the k8s OpenSandbox operator, and create a pool:\n```yaml\napiVersion: sandbox.opensandbox.io/v1alpha1\nkind: Pool\nmetadata:\n labels:\n app.kubernetes.io/name: sandbox-k8s\n app.kubernetes.io/managed-by: kustomize\n name: pool-sample\n namespace: opensandbox\nspec:\n template:\n metadata:\n labels:\n app: example\n spec:\n volumes:\n - name: sandbox-storage\n emptyDir: { }\n - name: opensandbox-bin\n emptyDir: { }\n initContainers:\n - name: task-executor-installer\n image: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/task-executor:v0.1.0\n command: [ \"/bin/sh\", \"-c\" ]\n args:\n - |\n cp /workspace/server /opt/opensandbox/bin/task-executor && \n chmod +x /opt/opensandbox/bin/task-executor\n volumeMounts:\n - name: opensandbox-bin\n mountPath: /opt/opensandbox/bin\n - name: execd-installer\n image: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:v1.0.7\n command: [ \"/bin/sh\", \"-c\" ]\n args:\n - |\n cp ./execd /opt/opensandbox/bin/execd && \n cp ./bootstrap.sh /opt/opensandbox/bin/bootstrap.sh &&\n chmod +x /opt/opensandbox/bin/execd &&\n chmod +x /opt/opensandbox/bin/bootstrap.sh\n volumeMounts:\n - name: opensandbox-bin\n mountPath: /opt/opensandbox/bin\n containers:\n - name: sandbox\n image: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\n command:\n - \"/bin/sh\"\n - \"-c\"\n - |\n /opt/opensandbox/bin/task-executor -listen-addr=0.0.0.0:5758 >/tmp/task-executor.log 2>&1\n env:\n - name: SANDBOX_MAIN_CONTAINER\n value: main\n - name: EXECD_ENVS\n value: /opt/opensandbox/.env\n - name: EXECD\n value: /opt/opensandbox/bin/execd\n volumeMounts:\n - name: sandbox-storage\n mountPath: /var/lib/sandbox\n - name: opensandbox-bin\n mountPath: /opt/opensandbox/bin\n tolerations:\n - operator: \"Exists\"\n capacitySpec:\n bufferMax: 3\n bufferMin: 1\n poolMax: 5\n poolMin: 0\n```\n\nStart the k8s OpenSandbox server:\n\n```shell\nuv pip install opensandbox-server\n\n# replace with your k8s cluster config, kubeconfig etc.\nopensandbox-server init-config ~/.sandbox.toml --example k8s\ncurl -o ~/batchsandbox-template.yaml https://raw.githubusercontent.com/alibaba/OpenSandbox/main/server/example.batchsandbox-template.yaml\n\nopensandbox-server\n```\n\n## Create and access the Code Interpreter Sandbox\n\n```shell\n# Install OpenSandbox packages\nuv pip install opensandbox opensandbox-code-interpreter\n\n# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY)\nuv run python examples/code-interpreter/main_use_pool.py\n```\n\nThe script creates a Sandbox + CodeInterpreter, runs a Python code snippet and prints stdout/result, then terminates the remote instance.\n\n## Environment variables\n\n- `SANDBOX_DOMAIN`: Sandbox service address (default: `localhost:8080`)\n- `SANDBOX_API_KEY`: API key if your server requires authentication\n- `SANDBOX_IMAGE`: Sandbox image to use (default: `sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2`)\n\n## Example output\n\n```text\n=== Verify Environment Variable ===\n[ENV Check] TEST_ENV value: test\n\n[ENV Result] 'test'\n\n=== Java example ===\n[Java stdout] Hello from Java!\n\n[Java stdout] 2 + 3 = 5\n\n[Java result] 5\n\n=== Go example ===\n[Go stdout] Hello from Go!\n3 + 4 = 7\n\n\n=== TypeScript example ===\n[TypeScript stdout] Hello from TypeScript!\n\n[TypeScript stdout] sum = 6\n```\n" }, { "path": "examples/code-interpreter/main.py", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport asyncio\nimport os\nfrom datetime import timedelta\n\nfrom code_interpreter import CodeInterpreter, SupportedLanguage\nfrom opensandbox import Sandbox\nfrom opensandbox.config import ConnectionConfig\n\n\nasync def main() -> None:\n domain = os.getenv(\"SANDBOX_DOMAIN\", \"localhost:8080\")\n api_key = os.getenv(\"SANDBOX_API_KEY\")\n image = os.getenv(\n \"SANDBOX_IMAGE\",\n \"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\",\n )\n\n config = ConnectionConfig(\n domain=domain,\n api_key=api_key,\n request_timeout=timedelta(seconds=60),\n )\n\n sandbox = await Sandbox.create(\n image,\n connection_config=config,\n entrypoint=[\"/opt/opensandbox/code-interpreter.sh\"]\n )\n\n async with sandbox:\n interpreter = await CodeInterpreter.create(sandbox=sandbox)\n\n # Python example: show runtime info and return a simple calculation.\n py_exec = await interpreter.codes.run(\n \"import platform\\n\"\n \"print('Hello from Python!')\\n\"\n \"result = {'py': platform.python_version(), 'sum': 2 + 2}\\n\"\n \"result\",\n language=SupportedLanguage.PYTHON,\n )\n print(\"\\n=== Python example ===\")\n for msg in py_exec.logs.stdout:\n print(f\"[Python stdout] {msg.text}\")\n if py_exec.result:\n for res in py_exec.result:\n print(f\"[Python result] {res.text}\")\n\n # Java example: print to stdout and return the final result line.\n java_exec = await interpreter.codes.run(\n \"System.out.println(\\\"Hello from Java!\\\");\\n\"\n \"int result = 2 + 3;\\n\"\n \"System.out.println(\\\"2 + 3 = \\\" + result);\\n\"\n \"result\",\n language=SupportedLanguage.JAVA,\n )\n print(\"\\n=== Java example ===\")\n for msg in java_exec.logs.stdout:\n print(f\"[Java stdout] {msg.text}\")\n if java_exec.result:\n for res in java_exec.result:\n print(f\"[Java result] {res.text}\")\n if java_exec.error:\n print(f\"[Java error] {java_exec.error.name}: {java_exec.error.value}\")\n\n # Go example: print logs and demonstrate a main function structure.\n go_exec = await interpreter.codes.run(\n \"package main\\n\"\n \"import \\\"fmt\\\"\\n\"\n \"func main() {\\n\"\n \" fmt.Println(\\\"Hello from Go!\\\")\\n\"\n \" sum := 3 + 4\\n\"\n \" fmt.Println(\\\"3 + 4 =\\\", sum)\\n\"\n \"}\",\n language=SupportedLanguage.GO,\n )\n print(\"\\n=== Go example ===\")\n for msg in go_exec.logs.stdout:\n print(f\"[Go stdout] {msg.text}\")\n if go_exec.error:\n print(f\"[Go error] {go_exec.error.name}: {go_exec.error.value}\")\n\n # TypeScript example: use typing and sum an array.\n ts_exec = await interpreter.codes.run(\n \"console.log('Hello from TypeScript!');\\n\"\n \"const nums: number[] = [1, 2, 3];\\n\"\n \"console.log('sum =', nums.reduce((a, b) => a + b, 0));\",\n language=SupportedLanguage.TYPESCRIPT,\n )\n print(\"\\n=== TypeScript example ===\")\n for msg in ts_exec.logs.stdout:\n print(f\"[TypeScript stdout] {msg.text}\")\n if ts_exec.error:\n print(f\"[TypeScript error] {ts_exec.error.name}: {ts_exec.error.value}\")\n\n await sandbox.kill()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "examples/code-interpreter/main_use_pool.py", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport asyncio\nimport os\nfrom datetime import timedelta\n\nfrom code_interpreter import CodeInterpreter, SupportedLanguage\nfrom opensandbox import Sandbox\nfrom opensandbox.config import ConnectionConfig\n\n\nasync def main() -> None:\n domain = os.getenv(\"SANDBOX_DOMAIN\", \"localhost:8080\")\n api_key = os.getenv(\"SANDBOX_API_KEY\")\n image = os.getenv(\n \"SANDBOX_IMAGE\",\n \"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\",\n )\n\n config = ConnectionConfig(\n domain=domain,\n api_key=api_key,\n request_timeout=timedelta(seconds=60),\n )\n\n sandbox = await Sandbox.create(\n image,\n connection_config=config,\n extensions={\"poolRef\":\"pool-sample\"},\n entrypoint=[\"/opt/opensandbox/code-interpreter.sh\"],\n env={\n \"TEST_ENV\": \"test\",\n },\n )\n\n async with sandbox:\n interpreter = await CodeInterpreter.create(sandbox=sandbox)\n\n # Verify environment variable is set\n print(\"\\n=== Verify Environment Variable ===\")\n env_check = await interpreter.codes.run(\n \"import os\\n\"\n \"test_env = os.getenv('TEST_ENV', 'NOT_SET')\\n\"\n \"print(f'TEST_ENV value: {test_env}')\\n\"\n \"test_env\",\n language=SupportedLanguage.PYTHON,\n )\n for msg in env_check.logs.stdout:\n print(f\"[ENV Check] {msg.text}\")\n if env_check.result:\n for res in env_check.result:\n print(f\"[ENV Result] {res.text}\")\n\n # Java example: print to stdout and return the final result line.\n java_exec = await interpreter.codes.run(\n \"System.out.println(\\\"Hello from Java!\\\");\\n\"\n \"int result = 2 + 3;\\n\"\n \"System.out.println(\\\"2 + 3 = \\\" + result);\\n\"\n \"result\",\n language=SupportedLanguage.JAVA,\n )\n print(\"\\n=== Java example ===\")\n for msg in java_exec.logs.stdout:\n print(f\"[Java stdout] {msg.text}\")\n if java_exec.result:\n for res in java_exec.result:\n print(f\"[Java result] {res.text}\")\n if java_exec.error:\n print(f\"[Java error] {java_exec.error.name}: {java_exec.error.value}\")\n\n # Go example: print logs and demonstrate a main function structure.\n go_exec = await interpreter.codes.run(\n \"package main\\n\"\n \"import \\\"fmt\\\"\\n\"\n \"func main() {\\n\"\n \" fmt.Println(\\\"Hello from Go!\\\")\\n\"\n \" sum := 3 + 4\\n\"\n \" fmt.Println(\\\"3 + 4 =\\\", sum)\\n\"\n \"}\",\n language=SupportedLanguage.GO,\n )\n print(\"\\n=== Go example ===\")\n for msg in go_exec.logs.stdout:\n print(f\"[Go stdout] {msg.text}\")\n if go_exec.error:\n print(f\"[Go error] {go_exec.error.name}: {go_exec.error.value}\")\n\n # TypeScript example: use typing and sum an array.\n ts_exec = await interpreter.codes.run(\n \"console.log('Hello from TypeScript!');\\n\"\n \"const nums: number[] = [1, 2, 3];\\n\"\n \"console.log('sum =', nums.reduce((a, b) => a + b, 0));\",\n language=SupportedLanguage.TYPESCRIPT,\n )\n print(\"\\n=== TypeScript example ===\")\n for msg in ts_exec.logs.stdout:\n print(f\"[TypeScript stdout] {msg.text}\")\n if ts_exec.error:\n print(f\"[TypeScript error] {ts_exec.error.name}: {ts_exec.error.value}\")\n\n await sandbox.kill()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "examples/codex-cli/README.md", "content": "# Codex/OpenAI CLI Example\n\nUse the official `@openai/codex` npm package to call OpenAI/Codex-like models in OpenSandbox.\n\n## Start OpenSandbox server [local]\n\nPre-pull the code-interpreter image (includes Node.js):\n\n```shell\ndocker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\n\n# use docker hub\n# docker pull opensandbox/code-interpreter:v1.0.2\n```\n\nStart the local OpenSandbox server, logs will be visible in the terminal:\n\n```shell\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker\nopensandbox-server\n```\n\n## Create and Access the Codex Sandbox\n\n```shell\n# Install OpenSandbox package\nuv pip install opensandbox\n\n# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY / OPENAI_API_KEY)\nuv run python examples/codex-cli/main.py\n```\n\nThe script installs the Codex CLI (`npm install -g @openai/codex@latest`) at runtime (Node.js is already in the code-interpreter image), then executes a simple request `codex exec \"Compute 1+1 and return JSON with keys result and reasoning.\" --skip-git-repo-check`. Auth is passed via `OPENAI_API_KEY`; you can override endpoint/model with `OPENAI_BASE_URL` / `OPENAI_MODEL`.\n\n## Environment Variables\n\n- `SANDBOX_DOMAIN`: Sandbox service address (default: `localhost:8080`)\n- `SANDBOX_API_KEY`: API key if your server requires authentication (optional for local)\n- `SANDBOX_IMAGE`: Sandbox image to use (default: `sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2`)\n- `OPENAI_API_KEY`: Your OpenAI API key (required)\n- `OPENAI_BASE_URL`: OpenAI API endpoint (default: `https://api.openai.com/v1`)\n- `OPENAI_MODEL`: Model to use (default: `gpt-4o-mini`)\n\n## References\n- [@openai/codex](https://www.npmjs.com/package/@openai/codex) - Official OpenAI Codex CLI\n" }, { "path": "examples/codex-cli/main.py", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport asyncio\nimport os\nfrom datetime import timedelta\n\nfrom opensandbox import Sandbox\nfrom opensandbox.config import ConnectionConfig\n\n\ndef _required_env(name: str) -> str:\n value = os.getenv(name)\n if not value:\n raise RuntimeError(f\"{name} is required\")\n return value\n\n\nasync def _print_execution_logs(execution) -> None:\n for msg in execution.logs.stdout:\n print(f\"[stdout] {msg.text}\")\n for msg in execution.logs.stderr:\n print(f\"[stderr] {msg.text}\")\n if execution.error:\n print(f\"[error] {execution.error.name}: {execution.error.value}\")\n\n\nasync def main() -> None:\n domain = os.getenv(\"SANDBOX_DOMAIN\", \"localhost:8080\")\n api_key = os.getenv(\"SANDBOX_API_KEY\")\n openai_api_key = _required_env(\"OPENAI_API_KEY\")\n openai_base_url = os.getenv(\"OPENAI_BASE_URL\", \"https://api.openai.com/v1\")\n openai_model = os.getenv(\"OPENAI_MODEL\", \"gpt-4o-mini\")\n image = os.getenv(\n \"SANDBOX_IMAGE\",\n \"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2\",\n )\n\n config = ConnectionConfig(\n domain=domain,\n api_key=api_key,\n request_timeout=timedelta(seconds=60),\n )\n\n # Inject OpenAI settings into container environment for CLI access\n env = {\n \"OPENAI_API_KEY\": openai_api_key,\n \"OPENAI_BASE_URL\": openai_base_url,\n \"OPENAI_MODEL\": openai_model,\n }\n # Drop None values to avoid overriding defaults inside CLI\n env = {k: v for k, v in env.items() if v is not None}\n\n sandbox = await Sandbox.create(\n image,\n connection_config=config,\n env=env,\n )\n\n async with sandbox:\n # Install Codex CLI (Node.js is already in the code-interpreter image)\n install_exec = await sandbox.commands.run(\n \"npm install -g @openai/codex@latest\"\n )\n await _print_execution_logs(install_exec)\n\n # Use Codex CLI to execute a command\n run_exec = await sandbox.commands.run(\n 'codex exec \"Compute 1+1=?.\" --skip-git-repo-check'\n )\n await _print_execution_logs(run_exec)\n\n await sandbox.kill()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "examples/desktop/Dockerfile", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nFROM ubuntu:22.04\n\n# Default to English; install locale support first, then other deps\nENV DEBIAN_FRONTEND=noninteractive \\\n LANG=en_US.UTF-8 \\\n LC_ALL=en_US.UTF-8 \\\n LANGUAGE=en_US:en\n\n#----------------------\n# Install locales first, then remaining dependencies\nRUN apt-get update \\\n && apt-get install -y locales \\\n && locale-gen en_US.UTF-8 \\\n && update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 LANGUAGE=en_US:en \\\n && apt-get install -y \\\n python3 \\\n python3-pip \\\n python3-websockify \\\n xvfb \\\n x11vnc \\\n xfce4 \\\n xfce4-terminal \\\n dbus-x11 \\\n xterm \\\n novnc \\\n fonts-dejavu-core \\\n net-tools \\\n ca-certificates \\\n --no-install-recommends \\\n && sed -i 's/DEFAULT_LOCALE = null;/DEFAULT_LOCALE = \"en\";/' /usr/share/novnc/app/localization.js \\\n && rm -rf /var/lib/apt/lists/*\n\n# Precreate X11 stuff\nRUN mkdir -p /tmp/.X11-unix\nRUN chmod 1777 /tmp/.X11-unix\n\n#----------------------\n# Create a non-root user\nRUN groupadd -r desktop && useradd -r -g desktop -G audio,video desktop \\\n && mkdir -p /home/desktop && chown -R desktop:desktop /home/desktop\n\n#----------------------\n# Configure user, etc\n\nWORKDIR /home/desktop\n\nUSER desktop\n\n# Default to bash\nCMD [\"bash\"]\n" }, { "path": "examples/desktop/README.md", "content": "# Desktop(VNC) Example\n\nLaunch Xvfb + x11vnc + fluxbox in OpenSandbox to provide a VNC-accessible desktop environment.\n\n## Build the Desktop Sandbox Image\n\nThe Dockerfile in this directory builds a sandbox image with desktop and VNC components pre-installed:\n\n```shell\ncd examples/desktop\ndocker build -t opensandbox/desktop:latest .\n```\n\nThis image includes:\n- Xvfb (virtual framebuffer X server)\n- x11vnc (VNC server)\n- XFCE desktop (panel, file manager, terminal)\n- Non-root user (desktop) for security\n\n## Start OpenSandbox server [local]\n\nPre-pull the desktop image:\n\n```shell\ndocker pull opensandbox/desktop:latest\n```\n\nStart the local OpenSandbox server:\n\n```shell\nuv pip install opensandbox-server\nopensandbox-server init-config ~/.sandbox.toml --example docker\nopensandbox-server\n```\n\n## Create and Access the Desktop Sandbox\n\n```shell\n# Install OpenSandbox package\nuv pip install opensandbox\n\nuv run python examples/desktop/main.py\n```\n\nThe script starts the desktop stack (Xvfb + XFCE + x11vnc) and also launches noVNC/websockify. It prints:\n- VNC endpoint (`endpoint.endpoint`) for native VNC clients, password from `VNC_PASSWORD` (default: `opensandbox`)\n- noVNC URL for browsers (`/vnc.html?host=...&port=...&path=...`)\n\nThe sandbox stays alive for 5 minutes by default; interrupt sooner with Ctrl+C. Uses the prebuilt desktop image by default.\n\n![Desktop shell](./screenshot_shell.jpg)\n![noVNC connect](./screenshot_connect.jpg)\n![noVNC password](./screenshot_password.jpg)\n![Desktop UI](./screenshot_desktop.jpg)\n\n## Environment Variables\n\n- `SANDBOX_DOMAIN`: Sandbox service address (default: `localhost:8080`)\n- `SANDBOX_API_KEY`: API key if your server requires authentication (optional for local)\n- `SANDBOX_IMAGE`: Sandbox image to use (default: `opensandbox/desktop:latest`)\n- `VNC_PASSWORD`: Password for VNC access (default: `opensandbox`)\n\n## References\n\n- [noVNC](https://github.com/novnc/noVNC)\n- [x11vnc](https://github.com/LibVNC/x11vnc)\n" }, { "path": "examples/desktop/build.sh", "content": "#!/bin/bash\n# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nset -ex\n\nTAG=${TAG:-latest}\n\ndocker buildx rm desktop-builder || true\n\ndocker buildx create --use --name desktop-builder\n\ndocker buildx inspect --bootstrap\n\ndocker buildx ls\n\ndocker buildx build \\\n -t opensandbox/desktop:${TAG} \\\n -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/desktop:${TAG} \\\n --platform linux/amd64,linux/arm64 \\\n --push \\\n .\n" }, { "path": "examples/desktop/main.py", "content": "# Copyright 2025 Alibaba Group Holding Ltd.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport asyncio\nimport os\nfrom datetime import timedelta\n\nfrom opensandbox import Sandbox\nfrom opensandbox.config import ConnectionConfig\nfrom opensandbox.models.execd import RunCommandOpts\n\n\ndef _required_env(name: str) -> str:\n value = os.getenv(name)\n if not value:\n raise RuntimeError(f\"{name} is required\")\n return value\n\n\nasync def _print_logs(label: str, execution) -> None:\n for msg in execution.logs.stdout:\n print(f\"[{label} stdout] {msg.text}\")\n for msg in execution.logs.stderr:\n print(f\"[{label} stderr] {msg.text}\")\n if execution.error:\n print(f\"[{label} error] {execution.error.name}: {execution.error.value}\")\n\n\nasync def main() -> None:\n domain = os.getenv(\"SANDBOX_DOMAIN\", \"localhost:8080\")\n api_key = os.getenv(\"SANDBOX_API_KEY\")\n image = os.getenv(\n \"SANDBOX_IMAGE\",\n \"opensandbox/desktop:latest\",\n )\n python_version = os.getenv(\"PYTHON_VERSION\", \"3.11\")\n vnc_password = os.getenv(\"VNC_PASSWORD\", \"opensandbox\")\n\n config = ConnectionConfig(\n domain=domain,\n api_key=api_key,\n request_timeout=timedelta(seconds=60),\n )\n\n sandbox = await Sandbox.create(\n image,\n connection_config=config,\n env={\n \"PYTHON_VERSION\": python_version,\n \"VNC_PASSWORD\": vnc_password,\n },\n )\n\n async with sandbox:\n # Desktop and VNC components are pre-installed in the image, just start them\n # Start virtual display, window manager, and VNC server (in background)\n xvfb_exec = await sandbox.commands.run(\n \"Xvfb :0 -screen 0 1280x800x24\",\n opts=RunCommandOpts(background=True),\n )\n await _print_logs(\"xvfb\", xvfb_exec)\n\n # Start XFCE session (provides panel, file manager, terminal)\n xfce_exec = await sandbox.commands.run(\n \"DISPLAY=:0 dbus-launch startxfce4\",\n opts=RunCommandOpts(background=True),\n )\n await _print_logs(\"xfce\", xfce_exec)\n\n vnc_exec = await sandbox.commands.run(\n \"x11vnc -display :0 \"\n \"-passwd \\\"$VNC_PASSWORD\\\" \"\n \"-forever -shared -rfbport 5900\",\n opts=RunCommandOpts(background=True),\n )\n await _print_logs(\"x11vnc\", vnc_exec)\n\n # Start noVNC/websockify to expose VNC over WebSocket/HTTP\n novnc_exec = await sandbox.commands.run(\n \"/usr/bin/websockify --web=/usr/share/novnc 6080 localhost:5900\",\n opts=RunCommandOpts(background=True),\n )\n await _print_logs(\"novnc\", novnc_exec)\n\n endpoint_vnc = await sandbox.get_endpoint(5900)\n endpoint_novnc = await sandbox.get_endpoint(6080)\n\n # Build noVNC URL with host/port/path for routed endpoint, e.g., host:port/proxy/6080\n novnc_host_port, novnc_path = endpoint_novnc.endpoint.split(\"/\", 1)\n novnc_host, novnc_port = novnc_host_port.split(\":\")\n novnc_url = (\n f\"http://{endpoint_novnc.endpoint}/vnc.html\"\n f\"?host={novnc_host}&port={novnc_port}&path={novnc_path}\"\n )\n\n print(\"\\nVNC endpoint (native clients):\")\n print(f\" {endpoint_vnc.endpoint}\")\n print(f\"Password: {vnc_password}\")\n\n print(\"\\nnoVNC (browser):\")\n print(f\" {novnc_url}\")\n print(f\"Password: {vnc_password}\")\n\n print(\"\\nKeeping sandbox alive for 5 minutes. Press Ctrl+C to exit sooner.\")\n try:\n await asyncio.sleep(300)\n except KeyboardInterrupt:\n print(\"Stopping...\")\n finally:\n await sandbox.kill()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n" }, { "path": "examples/docker-ossfs-volume-mount/README.md", "content": "# Docker OSSFS Volume Mount Example\n\nThis example demonstrates how to use the new SDK `ossfs` volume model to mount Alibaba Cloud OSS into sandboxes on Docker runtime.\n\n## What this example covers\n\n1. **Basic read-write mount** on an OSSFS backend.\n2. **Cross-sandbox sharing** on the same OSSFS backend path.\n3. **Two mounts, different OSS prefixes via `subPath`**.\n\n## Prerequisites\n\n### 1) Start OpenSandbox server (Docker runtime)\n\nMake sure your server host has:\n\n- Linux host OS (OSSFS backend is not supported when OpenSandbox Server runs on Windows)\n- `ossfs` installed\n- FUSE support enabled\n- writable local mount root for OSSFS (default `storage.ossfs_mount_root=/mnt/ossfs`)\n\n`storage.ossfs_mount_root` is **optional** if you use the default `/mnt/ossfs`.\nEven with on-demand mounting, the runtime still needs a deterministic host-side\nbase directory to place dynamic mounts (`//`).\n\nOptional config example:\n\n```toml\n[runtime]\ntype = \"docker\"\n\n[storage]\nossfs_mount_root = \"/mnt/ossfs\"\n```\n\nThen start the server:\n\n```bash\nopensandbox-server\n```\n\n### 2) Install Python SDK\n\n```bash\nuv pip install opensandbox\n```\n\nIf your PyPI version does not include OSSFS volume models yet, install from source:\n\n```bash\npip install -e sdks/sandbox/python\n```\n\n### 3) Prepare OSS credentials and target path\n\n```bash\nexport SANDBOX_DOMAIN=localhost:8080\nexport SANDBOX_API_KEY=your-api-key\nexport SANDBOX_IMAGE=ubuntu\n\nexport OSS_BUCKET=your-bucket\nexport OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com\nexport OSS_ACCESS_KEY_ID=your-ak\nexport OSS_ACCESS_KEY_SECRET=your-sk\n```\n\n## Run\n\n```bash\nuv run python examples/docker-ossfs-volume-mount/main.py\n```\n\n## Minimal SDK usage snippet\n\n```python\nfrom opensandbox import Sandbox\nfrom opensandbox.models.sandboxes import OSSFS, Volume\n\nsandbox = await Sandbox.create(\n image=\"ubuntu\",\n volumes=[\n Volume(\n name=\"oss-data\",\n ossfs=OSSFS(\n bucket=\"your-bucket\",\n endpoint=\"oss-cn-hangzhou.aliyuncs.com\",\n # version=\"2.0\", # optional, default is \"2.0\"\n accessKeyId=\"your-ak\",\n accessKeySecret=\"your-sk\",\n ),\n mountPath=\"/mnt/data\",\n subPath=\"train\", # optional\n readOnly=False, # optional\n )\n ],\n)\n```\n\n## Notes\n\n- Current implementation supports **inline credentials only** (`accessKeyId`/`accessKeySecret`).\n- Mounting is **on-demand** in Docker runtime (mount-or-reuse), not pre-mounted for all buckets.\n- `ossfs.version` exists in API/SDK with enum `\"1.0\" | \"2.0\"`, and defaults to `\"2.0\"` when omitted.\n- Docker runtime now applies **version-specific mount argument encoding**:\n - `1.0`: mounts via `ossfs ... -o