snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/_bundle.py

@@ -0,0 +1,240 @@
+"""Building a code bundle from a local tree.
+
+Collect, filter, hash and zip a directory into the archive that goes to a
+Snowflake stage. Pure functions over paths and bytes — no transport, no client.
+
+The credential exclusion is load-bearing, not hygiene: a project with a ``.env``
+beside ``main.py`` is the normal layout, and without this the bundle would upload
+it to the stage.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from snowflake.sandbox.exceptions import SandboxValidationError
+
+if TYPE_CHECKING:
+    from snowflake.sandbox._upload_plan import SkipReason, UploadPlan
+
+__all__ = [
+    "_collect_tree",
+    "_hash_files",
+    "_zip_files",
+    "_is_credential_path",
+    "_warn_notable_bundle_skips",
+]
+
+
+# Filenames a code bundle must never carry to a Snowflake stage (see the module
+# docstring for why this is load-bearing). Matched on the file name and on
+# directory components, case-insensitively.
+_CREDENTIAL_NAMES: frozenset[str] = frozenset(
+    {
+        ".env",
+        ".envrc",
+        ".netrc",
+        ".npmrc",
+        ".pypirc",
+        ".git-credentials",
+        "credentials",
+        "credentials.json",
+        "id_rsa",
+        "id_dsa",
+        "id_ecdsa",
+        "id_ed25519",
+        "service-account.json",
+        "connections.toml",
+    }
+)
+
+
+_CREDENTIAL_SUFFIXES: tuple[str, ...] = (".pem", ".key", ".p12", ".pfx", ".jks", ".keystore")
+
+
+_CREDENTIAL_DIRS: frozenset[str] = frozenset({".ssh", ".aws", ".gnupg", ".snowflake"})
+
+
+def _is_credential_path(rel: Path) -> bool:
+    """True when *rel* (relative to the bundle root) looks like a credential."""
+    parts = [p.lower() for p in rel.parts]
+    if any(p in _CREDENTIAL_DIRS for p in parts[:-1]):
+        return True
+    name = parts[-1]
+    if name in _CREDENTIAL_NAMES or name.startswith(".env."):
+        return True
+    return name.endswith(_CREDENTIAL_SUFFIXES)
+
+
+def _collect_tree(
+    src: Path,
+    *,
+    exclude: list[str] | None = None,
+    include: list[str] | None = None,
+) -> tuple[list[tuple[str, bytes]], UploadPlan]:
+    """Sorted ``(relpath, content)`` for every file under *src*, plus the plan that
+    says what was left out and why. Used by ``from_local``.
+
+    Selection is delegated to `_upload_plan`, which is the one walk the CLI and
+    `Sandbox.upload_dir` also use. This function used to own a second, weaker walk:
+    ``rglob`` with a four-entry skip set, which (a) reported nothing at all, so a
+    bundle that quietly lost a tree looked identical to a complete one, (b) never
+    recursed into a symlinked directory -- a pnpm/bazel workspace shipped without its
+    packages and without a word -- and (c) skipped no build output, so ``node_modules``
+    and ``dist`` rode along inside the zip. Sharing the engine fixes all three and
+    means the two walks cannot drift apart again.
+
+    The bytes are read here rather than in the engine: the engine plans an upload of
+    paths, and only this caller needs the contents in memory to zip them.
+    """
+    # Imported in-function: `_upload_plan` imports `_is_credential_path` from this
+    # module, so a module-scope import here would close that into a cycle. Same
+    # reason `_assemble` imports the predicate lazily.
+    from snowflake.sandbox._upload_plan import plan_directory
+
+    # `*.pyc` was a skip the old walk applied by suffix and the engine does not: its
+    # defaults prune `__pycache__` as a directory, which covers the common case but not
+    # a stray or legacy-layout `.pyc`. Kept as a bundle-scoped exclude rather than added
+    # to the engine's defaults, so this consolidation does not quietly change what
+    # `snow sandbox run` uploads. It leads, so a caller's own patterns can still
+    # re-admit it with `include=["*.pyc"]`.
+    plan = plan_directory(
+        src,
+        dest_root="/",
+        exclude=["*.pyc", *(exclude or [])],
+        include=include,
+        strip_root=True,
+    )
+    files: list[tuple[str, bytes]] = []
+    for item in plan.selected:
+        try:
+            files.append((item.rel, item.source.read_bytes()))
+        except OSError:
+            # Readable at stat time, gone or unreadable now. Recorded as a skip so the
+            # bundle still reports it rather than silently shrinking.
+            plan = _with_extra_skip(plan, item.rel, "unreadable")
+    files.sort(key=lambda pair: pair[0])
+    if not files:
+        # The CLI refuses this as "nothing to upload"; `from_local` used to build a
+        # zero-entry zip and hand back a sandbox with no code in it, which only shows
+        # up as an import failure inside the container.
+        raise SandboxValidationError(
+            f"no files to bundle from {src}: all {len(plan.skipped)} path(s) were "
+            f"filtered out ({_reason_summary(plan)}). Pass include= to re-admit a "
+            f"filtered path, or point from_local at the directory holding your code."
+        )
+    return files, plan
+
+
+def _reason_summary(plan: UploadPlan) -> str:
+    """``"91 default, 2 symlink-dir"`` -- the why-line for an empty-bundle error."""
+    counts = plan.skipped_by_reason()
+    return ", ".join(f"{n} {reason}" for reason, n in sorted(counts.items())) or "none"
+
+
+def _with_extra_skip(plan: UploadPlan, rel: str, reason: SkipReason) -> UploadPlan:
+    """A copy of *plan* with one more skip, and that file dropped from ``selected``."""
+    from snowflake.sandbox._upload_plan import Skipped, UploadPlan
+
+    return UploadPlan(
+        targets=plan.targets,
+        selected=tuple(s for s in plan.selected if s.rel != rel),
+        skipped=(*plan.skipped, Skipped(rel, reason)),
+        total_bytes=sum(s.size for s in plan.selected if s.rel != rel),
+        cwd=plan.cwd,
+        oversized=plan.oversized,
+    )
+
+
+def _hash_files(files: Sequence[tuple[str, bytes]]) -> str:
+    """Deterministic 16-hex content hash over ``(relpath, content)`` pairs, in the
+    order given. Independent of zip build time, so an unchanged tree hashes the
+    same and the image layer key is stable."""
+    import hashlib
+
+    hasher = hashlib.sha256()
+    for rel, data in files:
+        hasher.update(rel.encode())
+        hasher.update(data)
+    return hasher.hexdigest()[:16]
+
+
+def _zip_files(files: Sequence[tuple[str, bytes]]) -> bytes:
+    """Reproducible zip (fixed timestamps) of ``(relpath, content)`` pairs."""
+    import io
+    import zipfile
+
+    buf = io.BytesIO()
+    fixed_date = (2020, 1, 1, 0, 0, 0)
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for rel, data in files:
+            # compress_type has to be set on the ZipInfo, not just on the ZipFile:
+            # a hand-built ZipInfo defaults to ZIP_STORED and that default wins, so
+            # the ZipFile's compression= was silently ignored and every bundle went
+            # to the stage uncompressed. Only a ZipInfo built by the ZipFile itself
+            # (i.e. writestr with a str arcname) inherits it, and that path cannot
+            # pin the timestamp this function exists to fix.
+            entry = zipfile.ZipInfo(rel, date_time=fixed_date)
+            entry.compress_type = zipfile.ZIP_DEFLATED
+            zf.writestr(entry, data)
+    return buf.getvalue()
+
+
+# Reasons a bundle's caller wants to hear about. Ordinary filtering (`default`, an
+# explicit `rule`) is the feature working; these four mean the bundle may be missing
+# something the caller believes is in it.
+_NOTABLE_SKIPS: frozenset[str] = frozenset({"symlink-dir", "unreadable", "not-regular", "bad-name"})
+
+
+# Default-skipped directory names that are *also* plausible hand-written source
+# directories. Dropping `.git` or `__pycache__` needs no announcement; dropping
+# `build/` or `env/` might have dropped the project. `from_local` inherited these
+# from the shared engine's SKIP_DIRS, where they were only ever vetted against
+# `snow sandbox run`'s TARGETs, so a bundle can now lose a tree the old four-entry
+# skip set kept -- and `default` skips are otherwise silent by design.
+_AMBIGUOUS_SKIP_DIRS: frozenset[str] = frozenset({"env", "venv", "build", "dist", "target"})
+
+
+def _warn_notable_bundle_skips(src: Path, plan: UploadPlan) -> None:
+    """Warn when a bundle dropped something its author probably expected to ship.
+
+    `from_local` returns a `Sandbox`, so there is nowhere to hand a plan back to --
+    and a bundle missing a symlinked package tree is indistinguishable from a
+    complete one until the container fails to import it. A warning is the only
+    channel that reaches the caller without changing the return type.
+
+    Silent about `rule` skips, and about `default` skips other than the ambiguous
+    directory names above: filtering out ``node_modules`` is the intended behaviour,
+    and warning about it every time would train people to ignore the warning that
+    matters.
+    """
+    import warnings
+
+    ambiguous = sorted(
+        {k.rel for k in plan.skipped if k.reason == "default" and k.detail in _AMBIGUOUS_SKIP_DIRS}
+    )
+    if ambiguous:
+        warnings.warn(
+            f"code bundle from {src} skipped {len(ambiguous)} directory(ies) whose "
+            f"names are build output by default: {', '.join(ambiguous)}. If any of "
+            f"those hold source, re-admit them with include=.",
+            stacklevel=3,
+        )
+
+    notable = [k for k in plan.skipped if k.reason in _NOTABLE_SKIPS]
+    if not notable:
+        return
+    counts: dict[str, int] = {}
+    for item in notable:
+        counts[item.reason] = counts.get(item.reason, 0) + 1
+    summary = ", ".join(f"{n} {reason}" for reason, n in sorted(counts.items()))
+    sample = ", ".join(k.rel for k in notable[:3])
+    more = f" (and {len(notable) - 3} more)" if len(notable) > 3 else ""
+    warnings.warn(
+        f"code bundle from {src} left out {summary}: {sample}{more}. Symlinks are "
+        f"never followed; pass include= to re-admit a filtered path, or copy the "
+        f"target in place of the link.",
+        stacklevel=3,
+    )

snowflake/sandbox/_connection_resolve.py

@@ -0,0 +1,328 @@
+"""Connection resolution for ``snowflake.sandbox`` — split out of ``config.py``.
+
+We delegate connection handling to snowflake-connector-python end to end. The
+connector owns the file format (``config_manager.CONFIG_MANAGER`` — tomlkit type
+fidelity, file-permission checks, the config.toml/connections.toml merge) AND
+the resolution of a named connection into a live session: ``connect(
+connection_name=...)`` re-reads the connection, applies its own key aliases, and
+authenticates with whatever method the connection declares (password, key-pair,
+oauth token file, external browser). We hand it the connection name + file and
+take the session's REST bearer token — we do not rebuild connect() kwargs or
+re-layer env vars ourselves (that is snow-CLI behaviour the connector does not
+provide; the ``snow sandbox`` plugin gets it for free by using the CLI's own
+connection). The connector import stays lazy: ``import snowflake.sandbox`` never
+loads it — resolution happens on first use.
+
+Every name here is re-exported from ``config`` (``from ._connection_resolve
+import ...``) so ``snowflake.sandbox.config.<name>`` keeps resolving. The
+handful of things that stay in ``config`` (``Config``, ``_from_env``,
+``_config_files``, ``_warn_pat_fallback``, the ``_session_registry`` list) are
+imported lazily inside the functions that need them — a module-scope import back
+into ``config`` would close a cycle (``config`` imports this module to re-export
+it).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from snowflake.sandbox.config import Config
+
+
+def _append_port(host: str, raw_port: Any) -> str:
+    """Append ``:port`` to *host* when *raw_port* is a non-default (non-443) port.
+
+    A dev/regtest deployment reaches Snowflake on 8082, say, and that port belongs
+    in the REST endpoint too (``Config.base_url`` accepts a bare ``hostname[:port]``).
+    An absent, non-numeric, or 443 port is left off — 443 is the https default and a
+    junk value (a connector that reports a non-int ``port``) must not become a bogus
+    ``host:port``. One rule, shared by every place that turns connection/connector
+    fields into an endpoint.
+    """
+    try:
+        port_i = int(raw_port) if raw_port is not None else None
+    except (TypeError, ValueError):
+        port_i = None
+    if port_i and port_i != 443:
+        return f"{host}:{port_i}"
+    return host
+
+
+def _connector_config_manager() -> Any:
+    """The connector's ``CONFIG_MANAGER``, re-pointed at the current home and
+    re-read. Re-pointing mirrors what the connector itself does for a
+    ``connections_file_path=`` (see ``connection.py``) and picks up a
+    ``SNOWFLAKE_HOME`` (or a test's tmp home) set after the connector was first
+    imported. ``read_config`` also runs the file-permission checks we lacked."""
+    from snowflake.connector.config_manager import CONFIG_MANAGER
+
+    from snowflake.sandbox.config import _config_files
+
+    config_file, connections_file = _config_files()
+    CONFIG_MANAGER.file_path = config_file
+    for i, sl in enumerate(CONFIG_MANAGER._slices):
+        if sl.section == "connections":
+            CONFIG_MANAGER._slices[i] = sl._replace(path=connections_file)
+    CONFIG_MANAGER.read_config()
+    return CONFIG_MANAGER
+
+
+def _connection_fields(name: str) -> dict[str, Any]:
+    """The raw fields of connection *name*, straight from the connector's config
+    manager with native TOML types. Used only to read the account/host and to
+    detect a PAT before deciding how to authenticate — the login itself is handed
+    to ``connect(connection_name=...)``, which re-reads and normalises the file."""
+    from snowflake.sandbox.config import _config_files
+
+    cm = _connector_config_manager()
+    connections = cm["connections"]
+    if name not in connections:
+        raise ValueError(
+            f"connection {name!r} not found in {_config_files()[1]}; "
+            f"known connections: {sorted(connections)}"
+        )
+    return dict(connections[name])
+
+
+def _host_from_connection_fields(fields: dict[str, Any]) -> str:
+    """The endpoint for a connection's fields, without hand-rolling one.
+
+    An explicit ``host`` in the connection wins; otherwise the CONNECTOR's own
+    ``construct_hostname`` builds it, so ``region =`` is honored and a China region
+    gets the ``.cn`` top-level domain. Hand-rolling
+    ``f"{account}.snowflakecomputing.com"`` instead drops ``region`` (wrong account
+    endpoint) and forces ``.com`` (wrong TLD for cn- regions).
+
+    Shared by ``_config_from_connection`` and ``_dev.snowhouse_oauth_env`` so there
+    is exactly one host-derivation rule in the SDK. Note ``construct_hostname``
+    does not map ``_``->``-``; ``Config.base_url`` owns that normalisation, so a
+    caller that dials this host directly should go through ``Config``.
+    """
+    account = fields.get("account")
+    explicit = fields.get("host")
+    if explicit:
+        derived = str(explicit)
+    elif account:
+        from snowflake.connector.util_text import construct_hostname
+
+        region = fields.get("region")
+        derived = construct_hostname(str(region) if region else None, str(account))
+    else:
+        raise ValueError("connection has neither host nor account")
+    return _append_port(derived, fields.get("port"))
+
+
+def _default_connection_name() -> str | None:
+    """The connector's default connection name — but only when a matching
+    connection actually exists, so an absent implicit ``default`` falls back to
+    the environment instead of erroring. An explicit
+    ``SNOWFLAKE_DEFAULT_CONNECTION_NAME`` is returned even if missing, so the
+    downstream resolution failure is loud and actionable."""
+    cm = _connector_config_manager()
+    name = cm["default_connection_name"]  # env > config.toml > "default"
+    if os.environ.get("SNOWFLAKE_DEFAULT_CONNECTION_NAME"):
+        return str(name)
+    return str(name) if name in cm["connections"] else None
+
+
+def _underlying_connector_connection(obj: Any) -> Any:
+    """Return the ``snowflake.connector`` connection inside *obj*, or *obj* itself.
+
+    Accepts a Snowpark ``Session`` without importing snowpark: a Session is not a
+    connector connection (it has no ``.rest``) but exposes the one it wraps. Users
+    inside Streamlit-in-Snowflake and stored procedures hold a Session, not a
+    connection, and would otherwise have to reach into private attributes.
+
+    Duck-typed on purpose. Importing ``snowflake.snowpark`` to isinstance-check would
+    make an optional dependency mandatory and cost import time for everyone; the
+    attribute we need is the one Snowpark documents.
+    """
+    if getattr(obj, "rest", None) is not None:
+        return obj  # already a connector connection
+    inner = getattr(obj, "connection", None)
+    if inner is not None and getattr(inner, "rest", None) is not None:
+        return inner  # a Snowpark Session (or any wrapper exposing .connection)
+    return obj
+
+
+def _config_from_live_connection(conn: Any, role: str | None = None) -> Config:
+    """Build a Config from a connection the CALLER already opened.
+
+    The ``snow`` CLI resolves and opens the connection with its own machinery (its
+    global flags, its env overrides, every auth method) and hands the live object
+    here. The SDK then reuses this one connection for everything: the REST bearer is
+    ``connection.rest.token`` (read live via ``resolve_pat``, so a connector-renewed
+    token is picked up), and a stage PUT runs on the same connection instead of
+    opening a second one and re-deriving credentials.
+
+    Unlike ``_config_from_connection`` this does NOT append to ``_session_registry``:
+    the caller owns the connection's lifetime, and ``close_connections`` must not close a
+    connection it did not open. Holding it on ``Config.connection`` keeps a reference
+    without adopting it. ``connector_kwargs`` is left None — there is no name to
+    re-open by, and none is needed since the connection is reused directly.
+    """
+    import dataclasses
+
+    from snowflake.sandbox.config import _from_env
+
+    if role is not None:
+        raise ValueError(
+            "role= cannot be applied to an already-open connection: the role is "
+            "chosen at login and this session already exists. Pass connection=<name> "
+            "to mint a session at that role, or open the connection at that role."
+        )
+    conn = _underlying_connector_connection(conn)
+    rest = getattr(conn, "rest", None)
+    token = getattr(rest, "token", None) if rest is not None else None
+    if not token:
+        raise ValueError(
+            "connection= did not yield a session token. Pass a connection NAME from "
+            "~/.snowflake/connections.toml, a live snowflake.connector connection, a "
+            "Snowpark Session, or a Config built from raw credentials. If you passed an "
+            "open connection, check it has not been closed."
+        )
+    resolved = getattr(conn, "host", None)
+    if not resolved:
+        raise ValueError("the provided connection has no host")
+    resolved = _append_port(str(resolved), getattr(conn, "port", None))
+    base = _from_env()
+    return dataclasses.replace(
+        base,
+        account=getattr(conn, "account", None) or base.account,
+        host=resolved,
+        pat=str(token),
+        connector_kwargs=None,
+        connection=conn,
+    )
+
+
+def _config_from_connection(name: str, role: str | None = None) -> Config:
+    """Resolve a named connection into a Config by delegating to the connector.
+
+    Every non-PAT connection (password / oauth-token-file / key-pair / external
+    browser) is authenticated by ``connect(connection_name=...)``: the connector
+    re-reads the connection from the file, applies its own key aliases, and logs
+    in with the connection's declared method. We keep the session alive for the
+    process and use its REST bearer token. A PAT (``token`` field, or
+    ``authenticator = PROGRAMMATIC_ACCESS_TOKEN`` with the token in ``password``)
+    is exchanged for a session token instead, because a PAT handed through
+    verbatim comes back as 390303 "Invalid OAuth access token" from inside a
+    sandbox (whose mounted config authenticates ``authenticator=oauth``).
+
+    ``role`` overrides the connection's own ``role`` and is applied at login,
+    because a sandbox runs as the primary role of the session that created it —
+    see ``resolve_config``.
+    """
+    import dataclasses
+
+    import snowflake.connector  # lazy: loaded only when a connection is resolved
+
+    from snowflake.sandbox.config import _from_env, _session_registry, _warn_pat_fallback
+
+    fields = _connection_fields(name)  # also re-points CONFIG_MANAGER at the home
+    account = fields.get("account")
+    if not account:
+        raise ValueError(f"connection {name!r} has no account")
+    auth = str(fields.get("authenticator", "")).lower()
+    base = _from_env()
+
+    def _derived_host() -> str:
+        return _host_from_connection_fields(fields)
+
+    # Carried on the Config so a later stage PUT re-opens the SAME connection (its
+    # own credential + role) rather than replaying the minted session token (which
+    # fails 250001). We pass the connection NAME only — not secrets, and not a host
+    # or connections_file_path: the connector re-reads the file itself (config.toml
+    # or connections.toml) and derives/normalises the host. refresh_connection_config
+    # re-points CONFIG_MANAGER before that reuse.
+    # client_session_keep_alive: let the CONNECTOR keep this session alive
+    # server-side (a background heartbeat every master_validity/4 s) instead of a
+    # caller-side keepalive thread. Carried in connector_kwargs so a reconnect (and
+    # the stage-PUT reuse) inherit it. Not a silver bullet — a heartbeat cannot
+    # outlive the master token / OAuth grant, and a sub-heartbeat-interval session
+    # can still lapse — which is why the transport also re-mints reactively on a
+    # reauth response; but it removes the routine idle-expiry (390112) that made a
+    # snapshot go stale mid-workload.
+    reconnect: dict[str, Any] = {
+        "connection_name": name,
+        "login_timeout": 30,
+        "client_session_keep_alive": True,
+    }
+    if role is not None:
+        reconnect["role"] = role
+
+    def _with(pat: str, resolved_host: str, conn: Any | None = None) -> Config:
+        return dataclasses.replace(
+            base,
+            account=account,
+            host=resolved_host,
+            pat=pat,
+            connector_kwargs=dict(reconnect),
+            connection=conn,
+        )
+
+    def _session_token_from(conn: Any) -> Config:
+        _session_registry.append(conn)  # keep alive so the token stays valid
+        rest = getattr(conn, "rest", None)
+        if rest is None or rest.token is None:
+            raise ValueError(f"connection {name!r} did not yield a session token")
+        # Adopt the endpoint the connector actually connected to, rather than
+        # re-deriving one: it has already applied region, an explicit host, and an
+        # account identifier the REST TLS path can use.
+        resolved = _append_port(
+            str(getattr(conn, "host", None) or _derived_host()), getattr(conn, "port", None)
+        )
+        # Carry the live connection so ``refresh_config`` can renew the session
+        # token off it when this snapshot expires.
+        return _with(rest.token, resolved, conn)
+
+    pat = fields.get("token") or (
+        fields.get("password") if auth in ("programmatic_access_token", "pat") else None
+    )
+    if pat:
+        # Exchange the PAT for a session token via the connector's native PAT auth
+        # (AuthByPAT), which takes the token from ``token=`` with
+        # ``authenticator=PROGRAMMATIC_ACCESS_TOKEN`` — so we normalise the PAT into
+        # ``token`` regardless of which field the connection stored it in. Minting a
+        # real session (rather than replaying the PAT as the bearer) is what keeps
+        # Snowflake access from inside the sandbox from failing 390303, and lets an
+        # explicit role be applied.
+        # connection_name= so the CONNECTOR reads account/user/host/port/region off
+        # the file itself (verified: it honors the file's ``region`` alongside these
+        # overrides). Only the authenticator + token are overridden here; nothing
+        # about the endpoint is reassembled by us.
+        pat_kw: dict[str, Any] = {
+            "connection_name": name,
+            "login_timeout": 30,
+            "token": pat,
+            "authenticator": "PROGRAMMATIC_ACCESS_TOKEN",
+            "client_session_keep_alive": True,
+        }
+        if role is not None:
+            pat_kw["role"] = role
+        try:
+            return _session_token_from(snowflake.connector.connect(**pat_kw))
+        except Exception as exc:  # noqa: BLE001 - fall back to the PAT as bearer
+            if role is not None:
+                raise ValueError(
+                    f"connection {name!r}: could not mint a session at role "
+                    f"{role!r} from its programmatic access token "
+                    f"({type(exc).__name__}: {exc}). Scope the PAT to the role "
+                    "instead (ROLE_RESTRICTION), or use a password connection."
+                ) from exc
+            _warn_pat_fallback(name, exc)
+            return _with(pat, _derived_host())
+
+    # No credential pre-check of our own: the connector owns which fields and
+    # authenticators constitute a usable credential, and an allowlist here could
+    # only ever be a stale subset of that. The previous one rejected configs the
+    # connector accepts outright -- an inline ``private_key`` (it checked only
+    # ``private_key_file``/``private_key_path`` plus a ``private_key_raw`` that is
+    # not a connector field at all), the OAuth flow authenticators
+    # (``OAUTH_AUTHORIZATION_CODE`` / ``OAUTH_CLIENT_CREDENTIALS``, whose credential
+    # lives in ``oauth_client_id``/``oauth_client_secret``), ``ID_TOKEN``, and
+    # ``session_token``/``master_token``. Let ``connect()`` decide and report; its
+    # error names the actual missing field.
+    return _session_token_from(snowflake.connector.connect(**reconnect))

snowflake/sandbox/_deploy_spec.py

@@ -0,0 +1,56 @@
+"""``DeploySpec`` — the internal deploy IR.
+
+There is no manifest file: the decorator API (``@app.function``) and the CLI both
+produce a ``DeploySpec``, and ``deploy_spec``/``deploy_async`` both consume one.
+Kept in its own module so ``deploy`` can import it without a cycle.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from snowflake.sandbox._assemble import Bundle
+from snowflake.sandbox.egress import Egress, compile_egress
+from snowflake.sandbox.mount import StageMount
+from snowflake.sandbox.secret import Secret
+
+__all__ = ["DeploySpec"]
+
+
+@dataclass(frozen=True)
+class DeploySpec:
+    """Everything a deploy needs, in one object — the internal IR.
+
+    There is no manifest file: the decorator API (``@app.function``) and the CLI
+    both produce a ``DeploySpec``, and ``deploy_spec`` / ``deploy_async`` both
+    consume one.  Keeping it here (rather than in ``app``) lets ``deploy`` import
+    it without a cycle.
+
+    ``entry`` is the command the container runs.  ``egress``/``secrets`` are
+    combined by `egress_body()` — secrets are authored flat but nest on the wire.
+    ``stage_mounts`` are FUSE stage/workspace mounts passed through verbatim.
+
+    ``image`` is the catalog base name used for display + prod (SPCS) codegen and
+    launched directly (an ``Image`` is a reference to a catalog base).
+    """
+
+    image: str
+    entry: tuple[str, ...]
+    memory: str = "4g"
+    # Explicit CPU in cores, overriding what the memory tier would imply.
+    # None inherits the tier default, keeping the request byte-identical to one
+    # made before cpu existed.
+    cpu: float | None = None
+    code_stage: str | None = None
+    env: Mapping[str, str] = field(default_factory=dict)
+    egress: Egress | None = None
+    secrets: tuple[Secret, ...] = field(default_factory=tuple)
+    bundle: Bundle | None = None
+    stage_mounts: tuple[StageMount, ...] = field(default_factory=tuple)
+    project_name: str = "sandbox"
+    timeout_s: float = 3600.0
+
+    def egress_body(self) -> dict[str, object] | None:
+        """The ``egress`` request object, with ``secrets`` folded in."""
+        return compile_egress(self.egress, self.secrets)