refactor(sdk): decouple _ImageResolver builder lifecycle and sync push creds

- Split _ImageResolver into create_builder() / resolve() / resolve_with_builder()
  so callers (notably tests) can manage the builder sandbox themselves and inject
  environment-specific setup (e.g. iptables NAT) before the build runs.
  The original resolve() now reliably stops the builder in a finally block.
- Sandbox.start() now syncs Image.registry_{username,password} to the config so
  admin gets the credentials it needs to pull the image we just pushed.
- Default ROCK_IMAGE_BUILDER_IMAGE bumped to :latest so all instances pick up the
  builder image with bip=192.168.250.0/24 (avoids 172.17/16 collision with admin's
  docker0) and insecure-registries pre-configured for local test registries.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Issac-Newton

rock/env_vars.py

@@ -88,7 +88,7 @@
     "ROCK_ENVHUB_DEFAULT_DOCKER_IMAGE": lambda: os.getenv("ROCK_ENVHUB_DEFAULT_DOCKER_IMAGE", "python:3.11"),
     "ROCK_IMAGE_BUILDER_IMAGE": lambda: os.getenv(
         "ROCK_IMAGE_BUILDER_IMAGE",
-        "rock-n-roll-registry.cn-hangzhou.cr.aliyuncs.com/rock/rock-env-builder:0.2.1a1",
+        "rock-n-roll-registry.cn-hangzhou.cr.aliyuncs.com/rock/rock-env-builder:latest",
     ),
     "ROCK_ENVHUB_DB_URL": lambda: os.getenv(
         "ROCK_ENVHUB_DB_URL", f"sqlite:///{Path.home() / '.rock' / 'rock_envs.db'}"

rock/sdk/sandbox/client.py

@@ -175,6 +175,11 @@ async def start(self):
                 cluster=self.config.cluster,
                 extra_headers=self.config.extra_headers,
             )
+            # Sync image's registry credentials to SandboxConfig so admin can pull the
+            # built image. Don't override caller-provided creds.
+            if image_obj.registry_username and not self.config.registry_username:
+                self.config.registry_username = image_obj.registry_username
+                self.config.registry_password = image_obj.registry_password
 
         url = f"{self._url}/start_async"
         headers = self._build_headers()

rock/sdk/sandbox/image_resolver.py

@@ -95,6 +95,8 @@ class _ImageResolver:
     对于 dockerfile image，启动一个 builder sandbox 完成 DinD 构建和推送。
     """
 
+    BUILD_SESSION = "build"
+
     def __init__(
         self,
         *,
@@ -110,10 +112,12 @@ def __init__(
         self._builder_image = builder_image
         self._sandbox_factory = _sandbox_factory
 
-    async def resolve(self, image: Image) -> str:
-        if not image.needs_build:
-            return image.image_name
+    def create_builder(self) -> Sandbox:
+        """Construct (but do not start) the builder sandbox.
 
+        Exposed so callers can start, customise (e.g. inject test-only NAT rules), then
+        hand the running builder to :meth:`resolve_with_builder`.
+        """
         builder_image = self._builder_image or env_vars.ROCK_IMAGE_BUILDER_IMAGE
         builder_cfg = SandboxConfig(
             image=builder_image,
@@ -124,36 +128,55 @@ async def resolve(self, image: Image) -> str:
             auto_clear_seconds=60 * 30,
         )
         factory = self._sandbox_factory or Sandbox
-        builder = factory(builder_cfg)
-        session = "build"
-        try:
-            await builder.start()
-            await builder.create_session(CreateBashSessionRequest(session=session))
+        return factory(builder_cfg)
 
-            # ── Phase 1: Start dockerd ──
-            await self._run_script(builder, session, _DOCKERD_SCRIPT, "/tmp/rock_dockerd.sh", "DOCKERD_OK", 120)
-
-            # ── Phase 2: Build image ──
-            content_hash = image.content_hash()
-            context_path = await self._upload_context(builder, session, image)
-            build_script = self._gen_build_script(image, content_hash, context_path)
-            build_output = await self._run_script(builder, session, build_script, "/tmp/rock_build.sh", "BUILD_OK", 600)
-            if "CACHE_HIT" in build_output:
-                logger.info("Image %s cache hit, skipping push", image.image_name)
-                return image.image_name
-
-            # ── Phase 3: Login and push ──
-            push_script = self._gen_push_script(image)
-            await self._run_script(builder, session, push_script, "/tmp/rock_push.sh", "PUSH_OK", 300)
-
-            logger.info("Successfully built and pushed image %s", image.image_name)
+    async def resolve(self, image: Image) -> str:
+        """Resolve `image` by managing the builder lifecycle internally."""
+        if not image.needs_build:
             return image.image_name
+
+        builder = self.create_builder()
+        try:
+            await builder.start()
+            return await self.resolve_with_builder(image, builder)
         finally:
             try:
                 await builder.stop()
             except Exception:
                 logger.warning("Failed to stop builder sandbox: %s", builder.sandbox_id, exc_info=True)
 
+    async def resolve_with_builder(self, image: Image, builder: Sandbox) -> str:
+        """Run the build/push pipeline against an externally-managed, already-started
+        builder sandbox.
+
+        The caller owns `builder`'s lifecycle (start/stop) and is free to perform any
+        environment-specific setup (firewall rules, mounts, etc.) before calling this.
+        """
+        if not image.needs_build:
+            return image.image_name
+
+        session = self.BUILD_SESSION
+        await builder.create_session(CreateBashSessionRequest(session=session))
+
+        # ── Phase 1: Start dockerd ──
+        await self._run_script(builder, session, _DOCKERD_SCRIPT, "/tmp/rock_dockerd.sh", "DOCKERD_OK", 120)
+
+        # ── Phase 2: Build image ──
+        content_hash = image.content_hash()
+        context_path = await self._upload_context(builder, session, image)
+        build_script = self._gen_build_script(image, content_hash, context_path)
+        build_output = await self._run_script(builder, session, build_script, "/tmp/rock_build.sh", "BUILD_OK", 600)
+        if "CACHE_HIT" in build_output:
+            logger.info("Image %s cache hit, skipping push", image.image_name)
+            return image.image_name
+
+        # ── Phase 3: Login and push ──
+        push_script = self._gen_push_script(image)
+        await self._run_script(builder, session, push_script, "/tmp/rock_push.sh", "PUSH_OK", 300)
+
+        logger.info("Successfully built and pushed image %s", image.image_name)
+        return image.image_name
+
     async def _run_script(
         self, builder, session: str, script: str, remote_path: str, success_marker: str, timeout: int
     ) -> str: