bladekit 4.5.0__py3-none-any.whl

bladekit/_build.py

@@ -0,0 +1,337 @@
+"""Image-build resolution: create-or-find a build, stream build logs, wait.
+
+Used when ``@app.function(image=bladekit.Image(...))`` is first invoked. The build
+is idempotent by definition hash (image-dsl.md §7), so an unchanged image
+triggers zero rebuild. While a build is ``queued``/``building`` the SDK streams
+the build's SSE logs to the terminal (same mechanism as run logs), then reports
+success or raises an actionable :class:`bladekit.ImageBuildError`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from . import exceptions as exc
+
+_TERMINAL = frozenset({"succeeded", "failed"})
+
+
+def ensure_context_bundle(client: Any, data: bytes) -> str:
+    """Upload a from_dockerfile build context as a bundle; return its id.
+
+    Same flow as code bundles (create → presigned PUT → complete), so an
+    unchanged context deduplicates server-side by sha256 and uploads nothing.
+    The complete response is authoritative for the id: a concurrent identical
+    upload may adopt the winning ready bundle.
+    """
+    import hashlib
+
+    from ._constants import BUNDLE_MAX_BYTES
+
+    if len(data) > BUNDLE_MAX_BYTES:
+        raise exc.PayloadTooLargeError(
+            "BUNDLE_TOO_LARGE",
+            f"build context is {len(data) / 1e6:.1f} MB compressed, over the "
+            f"{BUNDLE_MAX_BYTES // (1024 * 1024)} MiB limit — add a .dockerignore "
+            "(large data belongs in a bladekit.Volume, not the image)",
+        )
+    sha = hashlib.sha256(data).hexdigest()
+    resp = client.create_bundle(len(data), sha)
+    bundle_id = resp["bundle"]["bundle_id"]
+    if resp.get("deduplicated"):
+        return bundle_id
+    client.upload_to_presigned(resp["upload_url"], data, "application/gzip")
+    completed = client.complete_bundle(bundle_id)
+    return completed.get("bundle_id", bundle_id)
+
+
+def resolve_image_build(
+    client: Any,
+    definition: dict,
+    definition_hash: str,
+    *,
+    context_data: Optional[bytes] = None,
+) -> str:
+    """Return the build_id of a ``succeeded`` build for this definition.
+
+    Creates the build if needed (idempotent), streams logs while it runs, and
+    raises ImageBuildError on failure.
+
+    Clean mode (default) collapses the whole build into a single ``building``
+    phase line — a spinner while it runs, then ``✓ building <short-ref> (dur)``
+    — and SUPPRESSES the raw build-step log chunks (that noise is only useful
+    when debugging). ``--verbose`` keeps the old behaviour: a start line, the
+    streamed build steps, per-state transitions, and an ``image built`` line.
+    """
+    from ._render import console, is_verbose, phase
+
+    context_bundle_id = (
+        ensure_context_bundle(client, context_data) if context_data else None
+    )
+    resp = client.create_image_build(
+        definition, definition_hash, context_bundle_id=context_bundle_id
+    )
+    build = resp["build"]
+    build_id = build["build_id"]
+    state = build.get("state")
+
+    if state == "succeeded":
+        # Already built (deduplicated): nothing to wait for, common fast path.
+        return build_id
+
+    if state == "failed":
+        # Per image-dsl.md §7, a POST whose last build is `failed` yields a NEW
+        # queued build; so seeing `failed` here would be a freshly-adopted
+        # terminal failure — surface it.
+        _raise_build_failed(build, build_id, definition_hash)
+
+    # queued / building (or an unknown non-terminal state): stream logs + wait.
+    if is_verbose():
+        console.print(
+            f"[cyan]building image[/cyan] [dim]{definition_hash[:12]}…[/dim] "
+            f"(build {build_id})"
+        )
+        final = _stream_build_logs(client, build_id)
+        final_state = final.get("state")
+        if final_state == "succeeded":
+            console.print(
+                f"[green]image built[/green] [dim]{definition_hash[:12]}…[/dim]"
+            )
+            return build_id
+        if final_state == "failed":
+            _raise_build_failed(final, build_id, definition_hash)
+        return _confirm_terminal(client, build_id, definition_hash)
+
+    # Clean mode: one collapsed phase line, build-step chunks suppressed.
+    with phase("building", f"{definition_hash[:8]}…") as ph:
+        final = _stream_build_logs(client, build_id, quiet=True)
+        final_state = final.get("state")
+        if final_state == "failed":
+            _raise_build_failed(final, build_id, definition_hash)
+        # Fetch the finished build once for the real short ref + timestamps
+        # (the SSE eof path drops both), so the resolved line shows the built
+        # ref and the true build duration rather than a wall-clock estimate.
+        if final_state != "succeeded":
+            build_id = _confirm_terminal(client, build_id, definition_hash)
+        fb = _safe_get_build(client, build_id)
+        if fb is not None:
+            from ._render import duration_str
+
+            ph.update(
+                meta=_short_image_ref(fb.get("image_ref"), definition_hash),
+                duration=duration_str(
+                    fb.get("started_at") or fb.get("created_at"),
+                    fb.get("finished_at"),
+                ),
+            )
+        else:
+            ph.update(meta=_short_image_ref(None, definition_hash))
+    return build_id
+
+
+def run_standalone_build(
+    client: Any,
+    definition: dict,
+    definition_hash: str,
+    *,
+    force: bool = False,
+    force_compression: bool = False,
+    context_data: Optional[bytes] = None,
+) -> dict:
+    """Drive a definition through ``POST /v1/images/builds`` to a terminal
+    state, returning the FULL final build record (``state``, ``image_ref``, …).
+
+    Used by the standalone ``blade image build`` CLI command
+    (docs/specs/phase2-dogfood-catalog-build.md §4b). Unlike
+    :func:`resolve_image_build` — the IMPLICIT path triggered by ``run``/
+    ``deploy``, which only ever returns a ``build_id`` — this always surfaces
+    the full record so the caller can print the digest-pinned ``image_ref`` or
+    emit ``--json``, and it threads through the explicit ``--force``/
+    ``--force-compression`` flags that the implicit path never sets.
+
+    Always streams quietly (build-step chunks suppressed), regardless of
+    ``--verbose``: build-log chunks are unconditionally tagged ``stdout``
+    server-side (``imagebuilder.go:492``), so surfacing them raw would leak
+    onto stdout and break ``blade image build --json``'s stdout-purity
+    contract (only the final JSON object may land on stdout). Use
+    ``blade image logs -f <build_id>`` for the raw step-by-step stream. The
+    collapsed ``building`` phase line (and any raised error) is rendered on
+    ``err_console`` instead of the default stdout ``console``, for the same
+    reason.
+
+    Raises :class:`bladekit.ImageBuildError` on a failed or unexpectedly
+    terminated build; the caller decides the process exit code.
+    """
+    from ._render import err_console, is_verbose, phase, duration_str
+
+    context_bundle_id = (
+        ensure_context_bundle(client, context_data) if context_data else None
+    )
+    resp = client.create_image_build(
+        definition,
+        definition_hash,
+        force=force,
+        force_compression=force_compression,
+        context_bundle_id=context_bundle_id,
+    )
+    build = resp["build"]
+    build_id = build["build_id"]
+    state = build.get("state")
+
+    if state == "succeeded":
+        # Already built (deduplicated): nothing to wait for, common fast path.
+        return build
+
+    if state == "failed":
+        # Per image-dsl.md §7, a POST whose last build is `failed` yields a NEW
+        # queued build; so seeing `failed` here would be a freshly-adopted
+        # terminal failure — surface it.
+        _raise_build_failed(build, build_id, definition_hash)
+
+    if is_verbose():
+        err_console.print(
+            f"[cyan]building image[/cyan] [dim]{definition_hash[:12]}…[/dim] "
+            f"(build {build_id})"
+        )
+
+    with phase("building", f"{definition_hash[:8]}…", stream=err_console) as ph:
+        final = _stream_build_logs(client, build_id, quiet=True)
+        if final.get("state") == "failed":
+            _raise_build_failed(final, build_id, definition_hash)
+        fb = _confirm_terminal_build(client, build_id, definition_hash)
+        ph.update(
+            meta=_short_image_ref(fb.get("image_ref"), definition_hash),
+            duration=duration_str(
+                fb.get("started_at") or fb.get("created_at"), fb.get("finished_at")
+            ),
+        )
+    return fb
+
+
+def _confirm_terminal_build(client: Any, build_id: str, definition_hash: str) -> dict:
+    """Final GET after the log stream ends: return the FULL build record on
+    success, raise ImageBuildError on ``failed``/any other non-terminal state.
+
+    Distinct from :func:`_confirm_terminal` (which only returns the
+    ``build_id``) because :func:`run_standalone_build` needs the full record
+    (``image_ref``, timestamps) for its own output.
+    """
+    build = client.get_image_build(build_id)
+    if build.get("state") == "succeeded":
+        return build
+    if build.get("state") == "failed":
+        _raise_build_failed(build, build_id, definition_hash)
+    raise exc.ImageBuildError(
+        build_id,
+        "INTERNAL",
+        f"build ended in unexpected state {build.get('state')!r}",
+        definition_hash=definition_hash,
+    )
+
+
+def _confirm_terminal(client: Any, build_id: str, definition_hash: str) -> str:
+    """Unknown terminal/aborted stream: a final GET decides success/failure."""
+    build = client.get_image_build(build_id)
+    if build.get("state") == "succeeded":
+        return build_id
+    if build.get("state") == "failed":
+        _raise_build_failed(build, build_id, definition_hash)
+    raise exc.ImageBuildError(
+        build_id,
+        "INTERNAL",
+        f"build ended in unexpected state {build.get('state')!r}",
+        definition_hash=definition_hash,
+    )
+
+
+def _safe_get_build(client: Any, build_id: str) -> Optional[dict]:
+    try:
+        return client.get_image_build(build_id)
+    except Exception:  # noqa: BLE001 — best-effort metadata for the phase line
+        return None
+
+
+def _short_image_ref(image_ref: Optional[str], definition_hash: str) -> str:
+    """Short human ref for a built image — ``built:7d448073…`` — never the full
+    sha256. Falls back to the definition hash when no image_ref is available."""
+    h: Optional[str] = None
+    if image_ref and "built:" in image_ref:
+        h = image_ref.rsplit("built:", 1)[-1]
+    elif image_ref and ":" in image_ref:
+        h = image_ref.rsplit(":", 1)[-1]
+    elif image_ref:
+        h = image_ref
+    h = h or definition_hash
+    return f"built:{h[:8]}…" if len(h) > 8 else f"built:{h}"
+
+
+def _raise_build_failed(build: dict, build_id: str, definition_hash: str) -> None:
+    err = build.get("error") or {}
+    raise exc.ImageBuildError(
+        build.get("build_id", build_id),
+        str(err.get("code", "IMAGE_BUILD_FAILED")),
+        str(err.get("message", "image build failed")),
+        definition_hash=definition_hash,
+    )
+
+
+def _stream_build_logs(client: Any, build_id: str, quiet: bool = False) -> dict:
+    """Stream a build's SSE logs to the terminal until eof; return final state.
+
+    Mirrors the run-log streaming loop: resilient to a dropped connection
+    (resume from the last seq), tolerant of unparseable events.
+
+    ``quiet=True`` consumes the stream WITHOUT printing anything (build-step
+    chunks and state transitions are suppressed) — used by the clean-mode
+    ``building`` phase, which shows a single collapsed line instead.
+    """
+    from ._render import print_log_chunk, print_state_transition, err_console
+
+    cursor: Optional[int] = None
+    final_state: Optional[str] = None
+    while True:
+        try:
+            for event, data, event_id in client.stream_build_logs(
+                build_id, cursor=cursor
+            ):
+                if event == "log":
+                    try:
+                        chunk = json.loads(data)
+                    except ValueError:
+                        continue
+                    if not quiet:
+                        print_log_chunk(chunk)
+                    if isinstance(chunk, dict) and "seq" in chunk:
+                        cursor = chunk["seq"]
+                    elif event_id is not None:
+                        try:
+                            cursor = int(event_id)
+                        except ValueError:
+                            pass
+                elif event == "state":
+                    try:
+                        payload = json.loads(data)
+                    except ValueError:
+                        continue
+                    final_state = payload.get("state")
+                    if not quiet:
+                        print_state_transition(final_state, payload.get("ts"))
+                elif event == "eof":
+                    return {"state": final_state}
+                elif event == "ping":
+                    continue
+            # Generator ended without eof: check whether the build is terminal.
+            build = client.get_image_build(build_id)
+            if build.get("state") in _TERMINAL:
+                return build
+            return {"state": final_state}
+        except exc.ConnectionFailed:
+            build = client.get_image_build(build_id)
+            if build.get("state") in _TERMINAL:
+                return build
+            err_console.print("[dim]build log stream dropped, reconnecting…[/dim]")
+            import time
+
+            time.sleep(0.5)
+            continue