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

snowflake/sandbox/_globs.py

@@ -0,0 +1,176 @@
+"""A gitignore-style path matcher, implemented on the standard library.
+
+Used by the CLI's ``run --include``/``--exclude`` so the patterns behave the way
+users already expect from ``.gitignore`` and ``.dockerignore``.
+
+Why this exists rather than ``fnmatch``: the repo's existing matcher
+(``_assemble._excluded``) is ``fnmatch`` over the relative path *or* the basename,
+and that dialect silently does the wrong thing for the spellings people reach for
+first. Measured:
+
+- ``--exclude node_modules`` matched **nothing** -- no file is *named* that.
+- ``--exclude "data/"`` matched **nothing** -- a trailing slash never matches a
+  file path.
+- ``--exclude "logs/*"`` recursed, because ``fnmatch``'s ``*`` crosses ``/``.
+- ``--exclude Makefile`` killed *every* nested ``Makefile``, with no way to anchor.
+
+Why not ``pathspec``: it is MPL-2.0, and every runtime dependency here is
+permissive (httpx BSD, typing-extensions PSF, the connector Apache-2.0). Taking it
+would put the first non-permissive licence into a shipped artifact for ~30 lines of
+pattern translation, and confining it to the ``cli`` extra would also keep the SDK's
+own ``Bundle`` include/exclude from ever converging on it.
+
+**This is a documented subset, not bit-for-bit git.** Supported: ``*`` (does not
+cross ``/``), ``?``, character classes, ``**/`` (any depth), ``/**`` (everything
+below), ``a/**/b``, a leading ``/`` or an interior ``/`` to anchor at the root, a
+trailing ``/`` to match a directory and its whole subtree, and a leading ``!`` to
+negate. Not supported: backslash escapes, POSIX classes like ``[[:alpha:]]``, and
+git's trailing-whitespace rules.
+
+One consequence is worth stating because it looks like a bug and is not: ``logs/*``
+excludes ``logs/x/y.txt``. ``*`` not crossing ``/`` governs how a single *segment*
+is matched, while a pattern that matches a directory takes that directory's whole
+subtree with it — exactly as git behaves.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+__all__ = ["GlobRule", "anchored_head", "compile_rules", "match_rules"]
+
+
+@dataclass(frozen=True)
+class GlobRule:
+    """One compiled pattern: the regex, whether it negates, and the source text.
+
+    ``source`` is carried so a caller can report *which* pattern decided a file's
+    fate — the reason the CLI can print per-rule exclusion counts.
+    """
+
+    regex: re.Pattern[str]
+    negated: bool
+    source: str
+
+
+def _translate(pattern: str) -> tuple[str, bool]:
+    """Return ``(regex_source, negated)`` for one gitignore-style *pattern*.
+
+    Raises `ValueError` on a pattern that cannot match anything, so a caller can
+    turn it into a usable error instead of a silent no-op.
+    """
+    raw = pattern
+    negated = pattern.startswith("!")
+    if negated:
+        pattern = pattern[1:]
+    if not pattern:
+        raise ValueError(f"empty pattern: {raw!r}")
+
+    # A trailing slash means "a *directory*, and everything under it". Since we match
+    # file paths, the matched part must therefore be a proper ancestor of the path --
+    # the subtree suffix becomes mandatory rather than optional below. Without that,
+    # `*.o/` would also match the plain file `main.o`, which git does not.
+    dir_only = pattern.endswith("/")
+    pattern = pattern.rstrip("/") or pattern
+    if not pattern.strip("/"):
+        raise ValueError(f"pattern matches nothing: {raw!r}")
+
+    # Anchored when the pattern has a slash anywhere other than its very end:
+    # 'a/b' and '/a' anchor at the root, 'a' and '*.log' match at any depth.
+    anchored = pattern.startswith("/") or "/" in pattern.strip("/")
+    pattern = pattern.lstrip("/")
+
+    out: list[str] = []
+    i, n = 0, len(pattern)
+    while i < n:
+        if pattern.startswith("**/", i):
+            out.append("(?:.*/)?")
+            i += 3
+        elif pattern.startswith("/**/", i):
+            # 'a/**/b' spans *zero* or more directories, so it must match 'a/b' too --
+            # which is why this case cannot fall through to the '/**' branch below
+            # (that would leave a stray separator and demand at least one directory).
+            out.append("/(?:.*/)?")
+            i += 4
+        elif pattern.startswith("/**", i):
+            out.append("/.*")
+            i += 3
+        elif pattern[i] == "*":
+            out.append("[^/]*")
+            i += 1
+        elif pattern[i] == "?":
+            out.append("[^/]")
+            i += 1
+        elif pattern[i] == "[":
+            close = pattern.find("]", i + 1)
+            if close == -1:
+                raise ValueError(f"unterminated character class in {raw!r}")
+            body = pattern[i + 1 : close]
+            if body.startswith("!"):
+                body = "^" + body[1:]
+            out.append(f"[{body}]")
+            i = close + 1
+        else:
+            out.append(re.escape(pattern[i]))
+            i += 1
+
+    prefix = "" if anchored else "(?:.*/)?"
+    # A non-directory pattern may match either the file itself or an ancestor
+    # directory of it, so the subtree is optional; a directory-only pattern must
+    # match an ancestor, so it is required.
+    suffix = "/.*$" if dir_only else "(?:/.*)?$"
+    return f"^{prefix}{''.join(out)}{suffix}", negated
+
+
+def anchored_head(rule: GlobRule) -> str | None:
+    """The literal first path segment *rule* is anchored to, or None.
+
+    None means "this rule can match at any depth, or at a segment this cannot read
+    literally" -- an unanchored pattern like ``*.log``, or one whose first segment
+    holds a wildcard. Callers use it to decide whether a rule could possibly match
+    inside a given directory, so None has to mean "assume it could": every caller
+    treats it as the conservative answer.
+
+    Derived from ``rule.source`` rather than the compiled regex because anchoring is
+    a property of the pattern text, and ``_translate`` has already thrown the
+    distinction away by the time it returns a regex.
+    """
+    pattern = rule.source[1:] if rule.source.startswith("!") else rule.source
+    if not (pattern.startswith("/") or "/" in pattern.strip("/")):
+        return None
+    head = pattern.lstrip("/").split("/", 1)[0]
+    if not head or any(c in head for c in "*?["):
+        return None
+    return head
+
+
+def compile_rules(patterns: object) -> tuple[GlobRule, ...]:
+    """Compile *patterns* in order, preserving it — later rules win.
+
+    Accepts any iterable of strings (or None) so callers can pass a Typer option
+    straight through.
+    """
+    if patterns is None:
+        return ()
+    if isinstance(patterns, str):  # a bare string is a caller mistake, not 1 pattern
+        raise TypeError("compile_rules expects an iterable of patterns, not a string")
+    rules: list[GlobRule] = []
+    for pattern in patterns:  # type: ignore[attr-defined]  # guarded above
+        regex_src, negated = _translate(pattern)
+        rules.append(GlobRule(re.compile(regex_src), negated, pattern))
+    return tuple(rules)
+
+
+def match_rules(rel: str, rules: tuple[GlobRule, ...]) -> GlobRule | None:
+    """Return the **last** rule matching *rel*, or None.
+
+    Last-match-wins is gitignore's rule, and returning the rule itself (rather than
+    a bool) is what lets a caller say *why* a file was dropped, and lets a negated
+    rule read as "kept by ``!x``" rather than merely "not excluded".
+    """
+    winner: GlobRule | None = None
+    for rule in rules:
+        if rule.regex.match(rel):
+            winner = rule
+    return winner

snowflake/sandbox/_hosts.py

@@ -0,0 +1,110 @@
+"""Host-pattern matching for egress rules.
+
+Pure domain-string logic, shared by the `Egress` spec and by `Secret`'s
+host-scope validation. No spec types, so both can import it without a cycle.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+__all__ = [
+    "host_covered_by",
+    "host_covered_by_all",
+    "common_parent",
+    "egress_group_for",
+    "ENFORCED_EGRESS_GROUPS",
+]
+
+
+def host_covered_by(host: str, allowed: Sequence[str]) -> bool:
+    """Is *host* covered by any pattern in *allowed*?
+
+    Matches the platform's own rule: a bare entry covers itself and every subdomain,
+    while an explicit `*.suffix` entry covers subdomains only.
+    """
+    h = host.lower().rstrip(".")
+    for entry in allowed:
+        pattern = str(entry).lower().strip().rstrip(".")
+        if not pattern:
+            continue
+        if pattern.startswith("*."):
+            if h.endswith(pattern[1:]):
+                return True
+        elif h == pattern or h.endswith("." + pattern):
+            return True
+    return False
+
+
+def host_covered_by_all(hosts: Sequence[str], pattern: str) -> bool:
+    """Does *pattern* cover every host in *hosts*?"""
+    return all(host_covered_by(h, [pattern]) for h in hosts)
+
+
+def common_parent(hosts: Sequence[str]) -> str | None:
+    """The nearest shared parent domain of *hosts*, or ``None`` if there is none.
+
+    Used only to name a concrete option in an error message — never to widen a
+    scope automatically. ``["api.github.com", "codeload.github.com"]`` yields
+    ``"github.com"``. Returns ``None`` when the hosts share fewer than two
+    trailing labels, or when the parent is one of the hosts already (that case
+    collapses and never reaches here).
+
+    Caveat: this is label arithmetic, not a public-suffix lookup, so for hosts
+    under a multi-label registrar (``a.co.uk``, ``b.co.uk``) the "parent" it
+    names is the registrar suffix. That is why the caller presents it as a
+    choice with its cost stated, rather than applying it.
+    """
+    label_sets = [h.lstrip("*.").strip(".").lower().split(".") for h in hosts if h]
+    if len(label_sets) < 2:
+        return None
+    shared: list[str] = []
+    for parts in zip(*(reversed(ls) for ls in label_sets), strict=False):
+        if len({*parts}) != 1:
+            break
+        shared.append(parts[0])
+    if len(shared) < 2:
+        return None
+    parent = ".".join(reversed(shared))
+    if any(parent == ".".join(ls) for ls in label_sets):
+        return None
+    return parent
+
+
+# The hosts each consumed group boolean actually covers. Informational: used to
+# explain reachability in errors/warnings. There is no caller-supplied per-host
+# allowlist to compare it against any more — Snowflake reserved
+# `EgressConfig.allowed_egress_hosts`, so this table plus an External Access
+# Integration is the whole of what a caller can grant. Note the groups apply in
+# the platform's DEFAULT mode only: under `allow_internet=False` they grant
+# nothing, so membership here does not imply reachability.
+ENFORCED_EGRESS_GROUPS: dict[str, tuple[str, ...]] = {
+    "github/dbt": (
+        "github.com",
+        "api.github.com",
+        "raw.githubusercontent.com",
+        "objects.githubusercontent.com",
+        "codeload.github.com",
+        "hub.getdbt.com",
+    ),
+    "pypi": ("pypi.org", "files.pythonhosted.org"),
+}
+
+
+def egress_group_for(host: str) -> str | None:
+    """The named platform group that makes *host* reachable, if any.
+
+    Two convenience groups exist: GitHub/dbt and PyPI. A host outside them is reached
+    with `allow_internet=True`, or granted by an External Access Integration — naming
+    it in `allowed_egress_hosts` is no longer a route, since the platform reserved
+    that field and ignores what it carries.
+
+    "Reachable" here is conditional on the platform's default mode: the groups have
+    no effect when `allow_internet=False`, so a hit from this function is a reason a
+    host *may* be reachable, not a guarantee that it is.
+    """
+    h = host.lower().strip().rstrip(".")
+    for group, hosts in ENFORCED_EGRESS_GROUPS.items():
+        if h in hosts:
+            return group
+    return None

snowflake/sandbox/_mcp_discovery.py

@@ -0,0 +1,288 @@
+"""Discovery of the account's EXTERNAL MCP SERVERs and this user's auth status.
+
+`list_mcp_servers` and its SQL helpers live here, split out of `mcp` because they
+are the only half that opens a Snowflake connection (``SHOW EXTERNAL MCP SERVERS``
++ ``SYSTEM$GET_USER_INTEGRATION_AUTHORIZATIONS``). The public name is re-exported
+from `snowflake.sandbox.mcp`, which is where it is documented and imported from.
+
+`McpServerInfo` (the return type) and the ``MCP_AUTH_*`` vocabulary stay in `mcp`
+alongside the value objects; this module imports them *inside* the functions that
+need them so the re-export edge ``mcp -> _mcp_discovery`` stays one-way — the
+deferred import runs after both modules are loaded, exactly like the
+`_connect_for_stage` import below.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Final
+
+from snowflake.sandbox.exceptions import SandboxAuthError, SandboxError
+
+if TYPE_CHECKING:
+    from snowflake.sandbox._stage import _ConfigCarrier
+    from snowflake.sandbox.mcp import McpServerInfo
+
+
+_SHOW_SCOPES: dict[str, str] = {
+    "account": " IN ACCOUNT",
+    "database": " IN DATABASE",
+    "schema": " IN SCHEMA",
+    "session": "",
+}
+
+_MCP_DISCOVERY_ERROR: Final = (
+    "could not list EXTERNAL MCP SERVERS — the account may not have the feature "
+    "enabled, or your role lacks privileges on it"
+)
+
+
+def _is_privilege_error(exc: BaseException) -> bool:
+    """True if a connector error looks like an auth/privilege failure.
+
+    Classified from the SQLSTATE and message rather than a raw errno table so the
+    call site can pick ``SandboxAuthError`` vs ``SandboxError`` without ever
+    surfacing the connector's own text.
+    """
+    sqlstate = getattr(exc, "sqlstate", None)
+    if sqlstate in ("42501", "28000"):  # insufficient privilege / auth
+        return True
+    text = str(exc).lower()
+    return any(
+        marker in text
+        for marker in (
+            "insufficient privileg",
+            "not authorized",
+            "unauthorized",
+            "access control",
+        )
+    )
+
+
+def _mcp_discovery_error(exc: BaseException) -> SandboxError:
+    """Map a raw discovery failure onto the documented public exception.
+
+    A privilege/authorization failure becomes ``SandboxAuthError``; anything else
+    becomes ``SandboxError``. The message is fixed and public-safe (no SQL text,
+    no server detail); the original error is preserved via ``from exc`` at the
+    raise site.
+    """
+    if _is_privilege_error(exc):
+        return SandboxAuthError(_MCP_DISCOVERY_ERROR)
+    return SandboxError(_MCP_DISCOVERY_ERROR)
+
+
+def list_mcp_servers(
+    *,
+    scope: str = "account",
+    connected_only: bool = False,
+    transport: _ConfigCarrier | None = None,
+    connection: Any | None = None,
+) -> list[McpServerInfo]:
+    """List the account's EXTERNAL MCP SERVERs with this user's auth status.
+
+    The point of the helper is that "what can I connect to, and have I connected
+    to it?" is answerable without leaving Python. It runs two statements on a
+    Snowflake connection resolved the same way the rest of the SDK resolves one
+    (named connection / config / env):
+
+    * ``SHOW EXTERNAL MCP SERVERS IN ACCOUNT`` — the objects and their API
+      integrations, already filtered by the server to what your role can see.
+    * ``SYSTEM$GET_USER_INTEGRATION_AUTHORIZATIONS`` over those integrations —
+      your per-user OAuth status for each.
+
+    Example:
+        for s in list_mcp_servers(connected_only=True):
+            print(s.name, s.fqn, s.status)
+
+    Parameters
+    ----------
+    scope:
+        ``"account"`` (default), ``"database"``, ``"schema"``, or ``"session"``
+        (no ``IN`` clause — the connection's current schema).
+    connected_only:
+        Return only servers this user has already authorized, i.e. the ones a
+        sandbox would actually receive.
+    transport:
+        INTERNAL seam — the type is private and unexported, so prefer ``connection=``.
+        Any object carrying a resolved `Config` (either client's transport). The
+        module-level config is used when omitted.
+    connection:
+        An already-open ``snowflake.connector`` connection to reuse. Left open on
+        return; a connection opened by this call is closed before returning.
+
+    Raises
+    ------
+    SandboxError
+        If the connection cannot be resolved, or the discovery statement fails --
+        most often because the account does not have the EXTERNAL MCP SERVER
+        feature enabled or the current role lacks privileges on it. A
+        privilege/authorization failure surfaces as ``SandboxAuthError``. The
+        message names no raw SQL or server detail.
+    """
+    # Deferred so the re-export edge (mcp -> _mcp_discovery) stays acyclic: the
+    # value object and its status vocabulary live in `mcp`, which re-exports this
+    # function. By the time it is called, `mcp` is fully loaded.
+    from snowflake.sandbox.mcp import MCP_AUTH_UNKNOWN, McpServerInfo, _coerce_auth_status
+
+    clause = _SHOW_SCOPES.get(scope)
+    if clause is None:
+        raise SandboxError(f"unknown scope {scope!r}: expected one of {sorted(_SHOW_SCOPES)!r}")
+
+    own_connection = connection is None
+    if connection is None:
+        # The SDK's one connection-resolution path: it reuses a named connection's
+        # own connect kwargs (and its role), which deriving credentials from the
+        # config does not. Named for stages because that is what first needed SQL;
+        # the resolution is not stage-specific.
+        from snowflake.sandbox._stage import _connect_for_stage
+
+        try:
+            connection, owns = _connect_for_stage(transport)
+        except Exception as exc:
+            # Connection resolution can raise a raw connector error (bad account,
+            # auth failure); surface the documented Sandbox* type, not internals.
+            raise _mcp_discovery_error(exc) from exc
+        # _connect_for_stage may reuse a live connection it does not own; close only
+        # what we opened, so a shared connection stays usable for later REST calls.
+        own_connection = owns
+    try:
+        try:
+            cur = connection.cursor()
+            # No interpolation of caller input: `clause` comes from _SHOW_SCOPES.
+            cur.execute(f"SHOW EXTERNAL MCP SERVERS{clause}")
+            rows = list(cur.fetchall())
+        except SandboxError:
+            raise
+        except Exception as exc:
+            # A feature-off account or a privilege gap raises a raw connector
+            # ``ProgrammingError`` (SQL-compilation / access-control) here; the
+            # most likely caller is a zero-context public user. Re-raise as the
+            # documented Sandbox* type with a message that leaks no SQL text.
+            raise _mcp_discovery_error(exc) from exc
+        cols = _column_index(cur)
+        servers = [_server_row(row, cols) for row in rows]
+        integrations = sorted({i for _, i in servers if i})
+        statuses = _auth_statuses(cur, integrations) if integrations else {}
+    finally:
+        if own_connection:
+            connection.close()
+
+    out: list[McpServerInfo] = []
+    for info, integration in servers:
+        raw_status = (
+            statuses.get(integration.upper(), MCP_AUTH_UNKNOWN) if integration else MCP_AUTH_UNKNOWN
+        )
+        status = _coerce_auth_status(raw_status)
+        entry = McpServerInfo(
+            name=info["name"],
+            fqn=info["fqn"],
+            api_integration=integration or None,
+            status=status,
+            enabled=info["enabled"],
+            comment=info["comment"],
+        )
+        if connected_only and not entry.connected:
+            continue
+        out.append(entry)
+    return out
+
+
+def _column_index(cur: Any) -> dict[str, int]:
+    """Map lowercased column name -> position from a cursor's description.
+
+    Read by name rather than position because two of the columns of ``SHOW
+    EXTERNAL MCP SERVERS`` -- ``api_integration`` and ``enabled`` -- are gated by
+    account parameters: an account can return the row without them, and
+    positional reads would silently shift.
+    """
+    idx: dict[str, int] = {}
+    for i, col in enumerate(cur.description or []):
+        name = col[0] if isinstance(col, (tuple, list)) else getattr(col, "name", None)
+        if isinstance(name, str):
+            idx[name.lower()] = i
+    return idx
+
+
+def _server_row(row: Sequence[Any], cols: dict[str, int]) -> tuple[dict[str, Any], str]:
+    """Turn one ``SHOW EXTERNAL MCP SERVERS`` row into its fields + integration."""
+
+    def get(col: str) -> Any:
+        i = cols.get(col)
+        return row[i] if i is not None and i < len(row) else None
+
+    name = get("name")
+    db = get("database_name")
+    schema = get("schema_name")
+    if not (name and db and schema):
+        raise SandboxError(
+            "SHOW EXTERNAL MCP SERVERS returned a row without name/database_name/"
+            f"schema_name (columns seen: {sorted(cols)!r})"
+        )
+    integration = get("api_integration")
+    enabled = get("enabled")
+    comment = get("comment")
+    return (
+        {
+            "name": str(name),
+            "fqn": f"{db}.{schema}.{name}",
+            "enabled": bool(enabled) if enabled is not None else None,
+            "comment": str(comment) if comment else None,
+        },
+        str(integration) if integration else "",
+    )
+
+
+def _auth_statuses(cur: Any, integrations: Sequence[str]) -> dict[str, str]:
+    """Per-user OAuth status per integration, keyed by UPPERCASED integration name.
+
+    One batched ``SYSTEM$GET_USER_INTEGRATION_AUTHORIZATIONS`` call, falling back
+    to one call per integration if the batch fails. The batch is not
+    all-or-nothing by accident: the function returns ``INTEGRATION_NOT_FOUND`` for
+    a missing integration but *throws* for one that does not support the user
+    OAuth flow, which would otherwise blind the whole listing over a single
+    unrelated integration.
+    """
+    # Deferred for the same reason as in `list_mcp_servers` (re-export acyclicity).
+    from snowflake.sandbox.mcp import MCP_AUTH_UNKNOWN
+
+    statuses = _auth_statuses_call(cur, integrations)
+    if statuses is not None:
+        return statuses
+    out: dict[str, str] = {}
+    for integration in integrations:
+        one = _auth_statuses_call(cur, [integration])
+        out.update(one if one is not None else {integration.upper(): MCP_AUTH_UNKNOWN})
+    return out
+
+
+def _auth_statuses_call(cur: Any, integrations: Sequence[str]) -> dict[str, str] | None:
+    """One SYSTEM$GET_USER_INTEGRATION_AUTHORIZATIONS call, or None if it failed."""
+    try:
+        # The function takes the array as a JSON string; bound as data (%s is
+        # pyformat, the connector's default paramstyle) so an integration name can
+        # never reach the SQL text.
+        cur.execute(
+            "SELECT SYSTEM$GET_USER_INTEGRATION_AUTHORIZATIONS(%s)",
+            (json.dumps(list(integrations)),),
+        )
+        row = cur.fetchone()
+    except Exception:
+        return None
+    if not row or not row[0]:
+        return None
+    try:
+        payload = json.loads(row[0])
+    except (TypeError, ValueError):
+        return None
+    out: dict[str, str] = {}
+    if isinstance(payload, list):
+        for item in payload:
+            if not isinstance(item, Mapping):
+                continue
+            name = item.get("integrationName") or item.get("integration_name")
+            status = item.get("status")
+            if isinstance(name, str) and isinstance(status, str):
+                out[name.upper()] = status.upper()
+    return out or None