gcw 0.1.0__py3-none-any.whl

gcw/__init__.py

@@ -0,0 +1,12 @@
+"""gcw ("gcloud web"): open Google Cloud console pages from the terminal.
+
+Package layout; dependencies point downwards only (``cli`` -> ``services`` ->
+``api`` / ``cache`` / ``context`` / ``web``):
+
+    cli       user-facing entry point: argument parsing, TAB completion, shell integration
+    services  one module per GCP service: console routes and resource listing
+    context   active account, project and region resolved from the gcloud configuration
+    cache     local resource cache that powers completion
+    api       access tokens and a minimal REST client for Google APIs
+    web       console URL building and opening the browser
+"""

gcw/__main__.py

@@ -0,0 +1,7 @@
+"""Run gcw as ``python -m gcw``; used by the background cache refresh."""
+
+import sys
+
+from gcw.cli.main import main
+
+sys.exit(main())

gcw/api/__init__.py

@@ -0,0 +1,6 @@
+"""Google API access: access tokens shared with gcloud and a minimal stdlib REST client.
+
+Used only off the completion path (background refresh, live lookups).
+
+Must not depend on ``cli`` or ``services``.
+"""

gcw/api/auth.py

@@ -0,0 +1,62 @@
+"""Access tokens for Google APIs, taken from the gcloud CLI.
+
+The token comes from the official ``gcloud auth print-access-token`` command
+(ADR-0016), so gcw never reads gcloud's credential store. The command takes
+about a second, which is acceptable because tokens are needed only off the
+completion path: background cache refresh and live lookups.
+"""
+
+import shutil
+import subprocess
+
+_TIMEOUT_SECONDS = 60
+
+# One token per account for the lifetime of the process. A refresh issues a
+# dozen requests within seconds, far below the token's one-hour lifetime.
+_tokens: dict[str | None, str] = {}
+
+
+class AuthError(RuntimeError):
+    """No access token is available; the message tells the user how to fix it."""
+
+
+def access_token(account: str | None = None) -> str:
+    """Return an OAuth access token for ``account``, as gcloud would use it.
+
+    Args:
+        account: Google account email (``core/account`` of the gcloud
+            configuration in use); ``None`` lets gcloud pick its active account.
+
+    Returns:
+        The access token.
+
+    Raises:
+        AuthError: gcloud is not installed, has no credentials for the account,
+            or the command failed or timed out.
+    """
+    if account not in _tokens:
+        _tokens[account] = _token_from_gcloud(account)
+    return _tokens[account]
+
+
+def _token_from_gcloud(account: str | None) -> str:
+    """Run ``gcloud auth print-access-token`` and return its output."""
+    # which() also finds gcloud.cmd on Windows, which a bare "gcloud" would not.
+    gcloud = shutil.which("gcloud")
+    if gcloud is None:
+        raise AuthError("gcloud not found on PATH; install the Google Cloud CLI and run `gcloud auth login`")
+
+    command = [gcloud, "auth", "print-access-token", "--verbosity=error"]
+    if account:
+        command += ["--account", account]
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, timeout=_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired:
+        raise AuthError(f"`gcloud auth print-access-token` timed out after {_TIMEOUT_SECONDS} s") from None
+
+    token = result.stdout.strip()
+    if result.returncode != 0 or not token:
+        reason = result.stderr.strip().splitlines()[-1] if result.stderr.strip() else "no token returned"
+        who = f" for {account}" if account else ""
+        raise AuthError(f"cannot get an access token{who} ({reason}); run `gcloud auth login`")
+    return token

gcw/api/client.py

@@ -0,0 +1,189 @@
+"""Minimal REST client for Google APIs on the standard library.
+
+Only what resource listing needs (ADR-0008): authenticated GET requests that
+return JSON, pagination over ``nextPageToken``, and running independent
+requests in parallel threads. Imported lazily by ``list_*`` functions, never
+on the completion path, because ``urllib.request`` pulls in ``ssl``.
+"""
+
+import json
+from collections.abc import Callable, Iterator
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, TypeVar
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+_TIMEOUT_SECONDS = 30
+_MAX_WORKERS = 8
+
+K = TypeVar("K")
+T = TypeVar("T")
+
+
+class ApiError(RuntimeError):
+    """A Google API request failed.
+
+    Attributes:
+        status: HTTP status code, or ``None`` when no response was received
+            (network error, timeout).
+    """
+
+    def __init__(self, message: str, status: int | None = None):
+        """Store the status code next to the message."""
+        super().__init__(message)
+        self.status = status
+
+
+def get_json(url: str, token: str, params: dict[str, str] | None = None) -> dict[str, Any]:
+    """Send an authenticated GET request and return the decoded JSON body.
+
+    Args:
+        url: Full API URL, e.g. ``"https://run.googleapis.com/v2/projects/p/locations/-/services"``.
+        token: OAuth access token (see ``gcw.api.auth``).
+        params: Query parameters to append.
+
+    Returns:
+        The response body; an empty dict for an empty body.
+
+    Raises:
+        ApiError: The server answered with an error status, or no answer arrived.
+    """
+    if params:
+        url = f"{url}?{urlencode(params)}"
+    request = Request(url, headers={"Authorization": f"Bearer {token}", "Accept": "application/json"})
+    try:
+        with urlopen(request, timeout=_TIMEOUT_SECONDS) as response:
+            body = response.read()
+    except HTTPError as error:
+        raise ApiError(_error_message(error), status=error.code) from None
+    except (URLError, TimeoutError) as error:
+        raise ApiError(f"request to {url} failed: {getattr(error, 'reason', error)}") from None
+    return json.loads(body) if body else {}
+
+
+def iter_pages(url: str, token: str, params: dict[str, str] | None = None) -> Iterator[dict[str, Any]]:
+    """Yield every page of a paginated endpoint, following ``nextPageToken``.
+
+    Args:
+        url: Full URL of the endpoint.
+        token: OAuth access token.
+        params: Extra query parameters sent with every page.
+
+    Yields:
+        Each decoded page, in order.
+
+    Raises:
+        ApiError: Any page request failed.
+    """
+    page_params = dict(params or {})
+    while True:
+        page = get_json(url, token, page_params)
+        yield page
+        next_token = page.get("nextPageToken")
+        if not next_token:
+            return
+        page_params["pageToken"] = next_token
+
+
+def list_all(url: str, token: str, items_key: str, params: dict[str, str] | None = None) -> list[dict[str, Any]]:
+    """Fetch every page of a ``list`` endpoint and return all items.
+
+    Args:
+        url: Full URL of the list endpoint.
+        token: OAuth access token.
+        items_key: Field holding the items in each page, e.g. ``"services"``.
+        params: Extra query parameters sent with every page.
+
+    Returns:
+        Items from all pages, in order.
+
+    Raises:
+        ApiError: Any page request failed.
+    """
+    return [item for page in iter_pages(url, token, params) for item in page.get(items_key, [])]
+
+
+def list_per_location(
+    locations_url: str, list_url: str, token: str, items_key: str
+) -> list[tuple[str, dict[str, Any]]]:
+    """List a collection in every location, for APIs that cannot aggregate with ``locations/-``.
+
+    First fetches the locations, then lists each one in parallel. A location
+    that fails is skipped; if every location fails, the first error is raised.
+
+    Args:
+        locations_url: Endpoint listing the locations; items have ``locationId``.
+        list_url: Endpoint listing the collection, with a ``{location}`` placeholder.
+        token: OAuth access token.
+        items_key: Field holding the items in each page of ``list_url``.
+
+    Returns:
+        ``(location, item)`` pairs for every item found.
+
+    Raises:
+        ApiError: The locations could not be listed, or no location answered.
+    """
+    locations = [item["locationId"] for item in list_all(locations_url, token, "locations")]
+    results = run_parallel({
+        location: (lambda location=location: list_all(list_url.format(location=location), token, items_key))
+        for location in locations
+    })
+    errors = [result for result in results.values() if isinstance(result, Exception)]
+    if errors and len(errors) == len(results):
+        raise errors[0]
+    return [
+        (location, item)
+        for location, items in results.items()
+        if not isinstance(items, Exception)
+        for item in items
+    ]
+
+
+def path_segment(resource_name: str, collection: str) -> str | None:
+    """Return the value that follows ``collection`` in a resource name.
+
+    Example: ``path_segment("projects/p/locations/eu1/services/api", "locations")``
+    returns ``"eu1"``. Also works on self links such as
+    ``"https://.../zones/eu1-b"``.
+
+    Returns:
+        The segment, or ``None`` if ``collection`` is not in the name.
+    """
+    parts = resource_name.split("/")
+    for index, part in enumerate(parts[:-1]):
+        if part == collection:
+            return parts[index + 1]
+    return None
+
+
+def run_parallel(tasks: dict[K, Callable[[], T]]) -> dict[K, T | Exception]:
+    """Run independent tasks in threads and collect each result or exception.
+
+    A failing task does not stop the others: its exception is returned in
+    place of a result, so the caller can report it and keep the rest.
+
+    Args:
+        tasks: Callables keyed by a name the caller chooses.
+
+    Returns:
+        For each key, the task's return value or the exception it raised.
+    """
+    if not tasks:
+        return {}
+    with ThreadPoolExecutor(max_workers=min(_MAX_WORKERS, len(tasks))) as pool:
+        futures = {key: pool.submit(task) for key, task in tasks.items()}
+    results: dict[K, T | Exception] = {}
+    for key, future in futures.items():
+        error = future.exception()
+        results[key] = error if error is not None else future.result()
+    return results
+
+
+def _error_message(error: HTTPError) -> str:
+    """Return the message from a Google API error body, or the HTTP reason."""
+    try:
+        detail = json.loads(error.read())["error"]["message"]
+    except (ValueError, KeyError, TypeError):
+        detail = error.reason
+    return f"HTTP {error.code}: {detail}"

gcw/cache/__init__.py

@@ -0,0 +1,6 @@
+"""Local resource cache: per account, project and resource type, refreshed in the background.
+
+Completion reads only from here and never waits for the network.
+
+Must not depend on ``cli`` or ``services``.
+"""

gcw/cache/refresh.py

@@ -0,0 +1,104 @@
+"""Refreshing the resource cache: fetching in parallel, and doing it in the background.
+
+``refresh`` fetches resources with the listing functions it is given (the
+cache layer does not import ``services``; the CLI passes them in) and writes
+every successful result. ``spawn_background`` runs ``gcw cache refresh`` as a
+detached process, so a stale cache is refreshed without the user waiting
+(ADR-0006). Never used on the completion path, which must not spawn processes.
+"""
+
+import os
+import subprocess
+import sys
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+from gcw.cache import store
+from gcw.context.resolve import Context
+
+# A background refresh normally takes seconds; a lock older than this belongs
+# to a process that died, so a new refresh may start.
+LOCK_SECONDS = 5 * 60
+
+Lister = Callable[[Context, str], list[store.Resource]]
+
+
+def refresh(context: Context, listers: dict[tuple[str, str], Lister]) -> dict[tuple[str, str], int | Exception]:
+    """Fetch resources of the given kinds in parallel and cache each successful result.
+
+    Args:
+        context: Account and project to refresh; ``context.project`` must be set.
+        listers: Listing functions keyed by ``(service, kind)``.
+
+    Returns:
+        For each key, the number of cached resources, or the exception that
+        prevented fetching that kind (e.g. an API disabled in the project).
+
+    Raises:
+        AuthError: No access token is available, so nothing can be fetched.
+    """
+    from gcw.api.auth import access_token
+    from gcw.api.client import run_parallel
+
+    token = access_token(context.account)
+    fetched = run_parallel({key: (lambda lister=lister: lister(context, token)) for key, lister in listers.items()})
+
+    results: dict[tuple[str, str], int | Exception] = {}
+    for (service, kind), resources in fetched.items():
+        if isinstance(resources, Exception):
+            results[(service, kind)] = resources
+        else:
+            store.write(context.account, context.project, service, kind, resources)
+            results[(service, kind)] = len(resources)
+    return results
+
+
+def lock_path(account: str | None, project: str) -> Path:
+    """Return the lock file that marks a background refresh of ``project`` in progress."""
+    return store.cache_dir() / (account or store.NO_ACCOUNT) / project / ".refresh.lock"
+
+
+def release_lock(account: str | None, project: str) -> None:
+    """Remove the background refresh lock; called by the refresh process when it ends."""
+    lock_path(account, project).unlink(missing_ok=True)
+
+
+def spawn_background(context: Context, service: str | None = None, kind: str | None = None) -> bool:
+    """Start ``gcw cache refresh --background`` as a detached process, unless one is running.
+
+    The child gets the same gcloud configuration and project, has no terminal
+    and outlives this process. It removes the lock when it finishes.
+
+    Args:
+        context: Account, project and configuration to refresh.
+        service: Refresh only this service; ``None`` refreshes everything.
+        kind: Refresh only this kind of ``service``.
+
+    Returns:
+        ``True`` if a process was started, ``False`` if a recent one holds the lock
+        or the process could not be started.
+    """
+    lock = lock_path(context.account, context.project)
+    try:
+        if time.time() - lock.stat().st_mtime < LOCK_SECONDS:
+            return False
+    except OSError:
+        pass  # no lock: nothing is running
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    lock.touch()
+
+    command = [sys.executable, "-m", "gcw", "cache", "refresh", "--background",
+               "-c", context.config.name, "-p", context.project]
+    command += [part for part in (service, kind) if part]
+    options: dict = {"stdin": subprocess.DEVNULL, "stdout": subprocess.DEVNULL, "stderr": subprocess.DEVNULL}
+    if os.name == "nt":
+        options["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        options["start_new_session"] = True
+    try:
+        subprocess.Popen(command, **options)
+    except OSError:
+        lock.unlink(missing_ok=True)
+        return False
+    return True

gcw/cache/store.py

@@ -0,0 +1,134 @@
+"""Resource cache entries and their storage on disk.
+
+A ``Resource`` is one cached resource: the flat ``{name, location, extra}``
+record of ADR-0006. Service modules produce them in their ``list_*`` functions;
+completion and the CLI read them back.
+
+Layout: one JSON file per account, project and resource kind::
+
+    <cache dir>/<account>/<project>/<service>.<kind>.json
+    {"fetched_at": <unix time>, "resources": [{"name": ..., "location": ..., "extra": {...}}]}
+
+Entries never expire hard. After ``SOFT_TTL_SECONDS`` an entry is stale: it is
+still used, and the caller starts a background refresh. Writes are atomic, so a
+reader never sees a half-written file. This module is on the completion path,
+so it imports nothing heavy.
+"""
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SOFT_TTL_SECONDS = 24 * 60 * 60
+
+# Directory name used when the gcloud configuration has no account.
+NO_ACCOUNT = "_"
+
+
+@dataclass(frozen=True)
+class Resource:
+    """One resource as stored in the cache.
+
+    Attributes:
+        name: Name the user types, e.g. a Cloud Run service name or a bucket.
+        location: Region or zone, or ``None`` for global resources.
+        extra: Service-specific details used to build URLs, e.g. a Composer
+            environment's ``airflow_uri`` or a repository's ``format``.
+    """
+
+    name: str
+    location: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> dict[str, Any]:
+        """Return the resource as a JSON-serialisable dict."""
+        return {"name": self.name, "location": self.location, "extra": self.extra}
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Resource":
+        """Build a resource from a dict written by ``to_json``."""
+        return cls(data["name"], data.get("location"), data.get("extra") or {})
+
+
+@dataclass(frozen=True)
+class CacheEntry:
+    """The cached resources of one kind, with the time they were fetched.
+
+    Attributes:
+        resources: The resources, in the order the API returned them.
+        fetched_at: Unix time of the fetch.
+    """
+
+    resources: list[Resource]
+    fetched_at: float
+
+    def is_stale(self, now: float | None = None) -> bool:
+        """Return whether the entry is older than the soft TTL and should be refreshed."""
+        return (now if now is not None else time.time()) - self.fetched_at > SOFT_TTL_SECONDS
+
+
+def cache_dir() -> Path:
+    """Return the root cache directory.
+
+    ``$GCW_CACHE_DIR`` wins; otherwise ``%LOCALAPPDATA%\\gcw`` on Windows and
+    ``$XDG_CACHE_HOME/gcw`` (default ``~/.cache/gcw``) elsewhere.
+    """
+    override = os.environ.get("GCW_CACHE_DIR")
+    if override:
+        return Path(override)
+    if os.name == "nt" and os.environ.get("LOCALAPPDATA"):
+        return Path(os.environ["LOCALAPPDATA"]) / "gcw"
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "gcw"
+
+
+def entry_path(account: str | None, project: str, service: str, kind: str) -> Path:
+    """Return the file that holds the resources of one kind."""
+    return cache_dir() / (account or NO_ACCOUNT) / project / f"{service}.{kind}.json"
+
+
+def read(account: str | None, project: str, service: str, kind: str) -> CacheEntry | None:
+    """Read the cached resources of one kind.
+
+    Returns:
+        The entry, or ``None`` if nothing is cached or the file is unreadable
+        (a corrupt file is treated as missing and gets rewritten on refresh).
+    """
+    try:
+        data = json.loads(entry_path(account, project, service, kind).read_text(encoding="utf-8"))
+        return CacheEntry([Resource.from_json(item) for item in data["resources"]], float(data["fetched_at"]))
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def write(account: str | None, project: str, service: str, kind: str, resources: list[Resource]) -> None:
+    """Replace the cached resources of one kind, atomically.
+
+    The data goes to a temporary file in the same directory, which then
+    replaces the entry in one step, so concurrent readers see either the old
+    or the new list.
+    """
+    # Imported here: tempfile is slow to import and completion only reads.
+    import tempfile
+
+    path = entry_path(account, project, service, kind)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    body = json.dumps({"fetched_at": time.time(), "resources": [r.to_json() for r in resources]})
+    descriptor, temporary = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as file:
+            file.write(body)
+        os.replace(temporary, path)
+    except BaseException:
+        Path(temporary).unlink(missing_ok=True)
+        raise
+
+
+def cached_projects(account: str | None) -> list[str]:
+    """Return the projects that have any cached resources for ``account``, sorted."""
+    try:
+        return sorted(entry.name for entry in (cache_dir() / (account or NO_ACCOUNT)).iterdir() if entry.is_dir())
+    except OSError:
+        return []

gcw/cli/__init__.py

@@ -0,0 +1,4 @@
+"""User-facing layer: argument parsing, command dispatch, TAB completion and shell integration.
+
+May depend on every other layer. Nothing else may import from here.
+"""