fogies 0.0.0.dev4__tar.gz → 0.0.0.dev6__tar.gz

{fogies-0.0.0.dev4 → fogies-0.0.0.dev6}/PKG-INFO

@@ -1,16 +1,20 @@
 Metadata-Version: 2.4
 Name: fogies
-Version: 0.0.0.dev4
+Version: 0.0.0.dev6
 Summary: 
 Author: James Fogarty
 Author-email: jayfo@users.noreply.github.com
 Requires-Python: >=3.14,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: boto3 (>=1.42.68,<2.0.0)
 Requires-Dist: filelock (>=3.25.2,<4.0.0)
-Requires-Dist: ollama (>=0.6.1,<0.7.0)
+Requires-Dist: ollama (>=0.6.2,<0.7.0)
 Requires-Dist: psutil (>=7.2.2,<8.0.0)
 Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: requests (>=2.33.0,<2.34.0)
+Requires-Dist: tenacity (>=9.1.4,<10.0.0)
+Requires-Dist: tomlkit (>=0.15.1,<0.16.0)
 Description-Content-Type: text/markdown
 
 # pyfogies

fogies-0.0.0.dev6/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "fogies"
+# Version follows semantic versioning <https://semver.org/>.
+version = "0.0.0-dev.6"
+description = ""
+authors = [
+    {name = "James Fogarty",email = "jayfo@users.noreply.github.com"}
+]
+readme = "README.md"
+requires-python = ">=3.14,<4.0"
+
+[tool.poetry]
+packages = [
+    {include = "fogies", from = "src"},
+]
+include = [
+    {path = "src/fogies/py.typed", format = ["sdist", "wheel"]},
+    {path = "src/fogies/includes/templates/aws.toml.template", format = ["sdist", "wheel"]},
+    {path = "src/fogies/includes/templates/poetry.toml.template", format = ["sdist", "wheel"]},
+    {path = "src/fogies/includes/templates/backend_status.toml.template", format = ["sdist", "wheel"]},
+]
+
+[tool.poetry.dependencies]
+# ^ allows all minor and patch releases.
+#   Example: ^1.2.3 will match 1.x.x versions >=1.2.3 and <2.0.0.
+# ~ allows only patch releases.
+#   Example: ~1.2.3 will match versions >=1.2.3 and <1.3.0.
+boto3 = "^1.42.68"
+filelock = "^3.25.2"
+ollama = "^0.6.2"
+psutil = "^7.2.2"
+pydantic = "^2.12.5"
+requests = "~2.33.0"
+tenacity = "^9.1.4"
+tomlkit = "^0.15.1"
+
+[tool.poetry.group.dev.dependencies]
+# ^ allows all minor and patch releases.
+#   Example: ^1.2.3 will match 1.x.x versions >=1.2.3 and <2.0.0.
+# ~ allows only patch releases.
+#   Example: ~1.2.3 will match versions >=1.2.3 and <1.3.0.
+basedpyright = "^1.36.1"
+black = "~26.5.1" # Black does not semver.
+boto3-stubs = {extras = ["logs", "s3"], version = "^1.43.70"}
+invoke = "^2.2.1"
+isort = "^8.0.1"
+poetry = "^2.2.1"
+pytest = "^9.0.2"
+semver = "^3.0.4"
+types-requests = "~2.33.0.20260712"
+
+[tool.basedpyright]
+typeCheckingMode = "recommended"
+pythonVersion = "3.14"
+include = ["src", "tasks", "tests"]
+allowedUntypedLibraries = ["invoke"]
+
+[tool.black]
+target-version = ["py314"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

fogies-0.0.0.dev6/src/fogies/aws_access_key.py

@@ -0,0 +1,148 @@
+"""IAM user and access key management, independent of invoke."""
+
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+from fogies.tools.aws_environ import AwsProfile
+from fogies.typing import boto_client_iam
+
+if TYPE_CHECKING:
+    from mypy_boto3_iam.type_defs import AccessKeyMetadataTypeDef
+
+
+class _IamAccessKeyInfo(BaseModel):
+    key_id: str
+    status: str
+    created: datetime.datetime | None
+    last_used: datetime.datetime | None
+
+
+class IamAccessKeys(BaseModel):
+    current: _IamAccessKeyInfo | None  # newest key
+    previous: _IamAccessKeyInfo | None  # oldest key; only present when two keys exist
+
+
+class _IamUserInfo(BaseModel):
+    username: str
+    keys: IamAccessKeys
+
+
+def get_keys(*, username: str) -> IamAccessKeys:
+    """Return the access keys for an IAM user as current (newest) and previous (oldest).
+
+    Raises ValueError if the IAM user does not exist.
+    """
+    iam = boto_client_iam()
+    try:
+        raw_keys = iam.list_access_keys(UserName=username)["AccessKeyMetadata"]
+    except iam.exceptions.NoSuchEntityException as exc:
+        raise ValueError("IAM user '{}' not found.".format(username)) from exc
+    sorted_keys = sorted(
+        raw_keys,
+        key=lambda k: k.get("CreateDate") or datetime.datetime.min,
+        reverse=True,
+    )
+
+    def _to_info(raw_key: AccessKeyMetadataTypeDef) -> _IamAccessKeyInfo:
+        key_id = raw_key.get("AccessKeyId", "")
+        last_used_response = iam.get_access_key_last_used(AccessKeyId=key_id)
+        last_used = last_used_response["AccessKeyLastUsed"].get("LastUsedDate")
+        return _IamAccessKeyInfo(
+            key_id=key_id,
+            status=raw_key.get("Status", ""),
+            created=raw_key.get("CreateDate"),
+            last_used=last_used,
+        )
+
+    return IamAccessKeys(
+        current=_to_info(sorted_keys[0]) if len(sorted_keys) >= 1 else None,
+        previous=_to_info(sorted_keys[1]) if len(sorted_keys) >= 2 else None,
+    )
+
+
+def list_users() -> list[_IamUserInfo]:
+    """List all IAM users (sorted by name) and their access keys."""
+    iam = boto_client_iam()
+    raw_users = [
+        user
+        for page in iam.get_paginator("list_users").paginate()
+        for user in page["Users"]
+    ]
+    users = [
+        _IamUserInfo(
+            username=user["UserName"], keys=get_keys(username=user["UserName"])
+        )
+        for user in raw_users
+    ]
+    return sorted(users, key=lambda u: u.username)
+
+
+def create_user(*, username: str) -> AwsProfile:
+    """Create a new IAM user and an access key. Raises if the IAM user already exists."""
+    iam = boto_client_iam()
+    try:
+        _ = iam.get_user(UserName=username)
+        raise ValueError("IAM user '{}' already exists.".format(username))
+    except iam.exceptions.NoSuchEntityException:
+        pass
+
+    _ = iam.create_user(UserName=username)
+    key = iam.create_access_key(UserName=username)["AccessKey"]
+    return AwsProfile(
+        name=username,
+        aws_access_key_id=key["AccessKeyId"],
+        aws_secret_access_key=key["SecretAccessKey"],
+    )
+
+
+def rotate_key(*, username: str, protected_key_ids: set[str]) -> AwsProfile:
+    """Create a new access key for an IAM user, deleting the previous key first if one exists.
+
+    Raises ValueError if the previous key is in protected_key_ids.
+    """
+    existing = get_keys(username=username)
+    if existing.previous is not None:
+        delete_key(
+            username=username,
+            key_id=existing.previous.key_id,
+            protected_key_ids=protected_key_ids,
+        )
+
+    iam = boto_client_iam()
+    key = iam.create_access_key(UserName=username)["AccessKey"]
+    return AwsProfile(
+        name=username,
+        aws_access_key_id=key["AccessKeyId"],
+        aws_secret_access_key=key["SecretAccessKey"],
+    )
+
+
+def delete_key(*, username: str, key_id: str, protected_key_ids: set[str]) -> None:
+    """Delete a specific access key for the IAM user.
+
+    Raises ValueError if key_id is in protected_key_ids.
+    """
+    if key_id in protected_key_ids:
+        raise ValueError("Refusing to delete protected key '{}'.".format(key_id))
+    _ = boto_client_iam().delete_access_key(UserName=username, AccessKeyId=key_id)
+
+
+def delete_user(*, username: str, protected_usernames: set[str]) -> None:
+    """Delete an IAM user.
+
+    Raises ValueError if the IAM user does not exist, still has access keys, or is protected.
+    """
+    if username in protected_usernames:
+        raise ValueError("Refusing to delete protected IAM user '{}'.".format(username))
+    iam = boto_client_iam()
+    try:
+        keys = iam.list_access_keys(UserName=username)["AccessKeyMetadata"]
+    except iam.exceptions.NoSuchEntityException as exc:
+        raise ValueError("IAM user '{}' not found.".format(username)) from exc
+    if keys:
+        raise ValueError("IAM user '{}' still has an access key.".format(username))
+    _ = iam.delete_user(UserName=username)

fogies-0.0.0.dev6/src/fogies/includes/templates/aws.toml.template

@@ -0,0 +1,6 @@
+# AWS credentials. Keyed by profile name.
+# https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html
+
+# [profile-name]
+# aws_access_key_id = "..."
+# aws_secret_access_key = "..."

fogies-0.0.0.dev6/src/fogies/includes/templates/backend_status.toml.template

@@ -0,0 +1,5 @@
+# Tracks this Terraform backend and the states using it.
+# Managed by tasks for Terraform apply and destroy.
+
+[backend]
+applied = false

fogies-0.0.0.dev6/src/fogies/includes/templates/poetry.toml.template

@@ -0,0 +1,5 @@
+# Poetry credentials for publishing to PyPI.
+# See https://pypi.org/manage/account/token/.
+
+# [pypi]
+# api_key = "pypi-..."

fogies-0.0.0.dev6/src/fogies/ready_poll.py

@@ -0,0 +1,63 @@
+"""Readiness-polling profiles built on tenacity.
+
+Call sites should use one of the named profiles below rather than inventing
+timing/exception values locally. Add a new profile here if a case genuinely
+needs different numbers.
+"""
+
+import dataclasses
+import socket
+
+import requests
+import tenacity
+
+# Exceptions that mean DNS resolution hasn't propagated yet.
+READY_POLL_EXCEPTIONS_DNS: tuple[type[BaseException], ...] = (socket.gaierror,)
+
+# Exceptions that mean an HTTP endpoint is not yet ready.
+READY_POLL_EXCEPTIONS_HTTP: tuple[type[BaseException], ...] = (
+    requests.exceptions.ConnectionError,
+    requests.exceptions.HTTPError,
+    requests.exceptions.SSLError,
+    requests.exceptions.Timeout,
+    TimeoutError,
+)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ReadyPollTiming:
+    """Timeout and poll-interval pair for ready_poll, both in seconds."""
+
+    timeout_seconds: float
+    poll_interval_seconds: float
+
+
+# Profile for something that can take minutes to become ready.
+READY_POLL_TIMING_LONG = ReadyPollTiming(
+    timeout_seconds=300.0, poll_interval_seconds=5.0
+)
+
+# Profile for something expected ready within seconds.
+READY_POLL_TIMING_SHORT = ReadyPollTiming(
+    timeout_seconds=10.0, poll_interval_seconds=0.5
+)
+
+
+def ready_poll(
+    *,
+    exceptions: type[BaseException] | tuple[type[BaseException], ...],
+    timing: ReadyPollTiming,
+    reraise: bool = True,
+) -> tenacity.Retrying:
+    """Retry policy for polling until a resource becomes ready or *timing.timeout_seconds* elapses.
+
+    Retries only on *exceptions*; any other exception propagates immediately.
+    On giving up, re-raises the last *exceptions* instance unless *reraise* is
+    False, in which case a `tenacity.RetryError` is raised instead.
+    """
+    return tenacity.Retrying(
+        retry=tenacity.retry_if_exception_type(exceptions),
+        wait=tenacity.wait_fixed(timing.poll_interval_seconds),
+        stop=tenacity.stop_after_delay(timing.timeout_seconds),
+        reraise=reraise,
+    )

fogies-0.0.0.dev6/src/fogies/retry.py

@@ -0,0 +1,48 @@
+"""Retry policy for flaky one-off operations, built on tenacity.
+
+Pass *log_path* to append a line for each retried failure. This is for
+retries whose cause isn't already well understood and is worth investigating;
+well-understood retries don't need it. Nothing is written, and no file is
+created, unless a retry actually happens.
+"""
+
+import pathlib
+from collections.abc import Callable
+from datetime import datetime
+from typing import TypeVar
+
+import tenacity
+
+_T = TypeVar("_T")
+
+
+def _log_retry(log_path: pathlib.Path) -> Callable[[tenacity.RetryCallState], None]:
+    def log_it(retry_state: tenacity.RetryCallState) -> None:
+        outcome = retry_state.outcome
+        assert outcome is not None and outcome.failed
+        exception = outcome.exception()
+        assert exception is not None
+        line = "{} attempt {} raised {}: {}\n".format(
+            datetime.now().isoformat(timespec="seconds"),
+            retry_state.attempt_number,
+            type(exception).__name__,
+            exception,
+        )
+        with log_path.open("a", encoding="utf-8") as f:
+            _ = f.write(line)
+
+    return log_it
+
+
+def retry_transient(
+    *,
+    exceptions: type[BaseException] | tuple[type[BaseException], ...],
+    log_path: pathlib.Path | None = None,
+) -> Callable[[Callable[[], _T]], Callable[[], _T]]:
+    """Retry profile for a flaky one-off operation, with no backoff."""
+    return tenacity.retry(
+        retry=tenacity.retry_if_exception_type(exceptions),
+        stop=tenacity.stop_after_attempt(5),
+        reraise=True,
+        before_sleep=_log_retry(log_path) if log_path is not None else None,
+    )

fogies-0.0.0.dev6/src/fogies/tasks/access_key.py

@@ -0,0 +1,286 @@
+"""Tasks for managing IAM users and access keys."""
+
+from __future__ import annotations
+
+import contextlib
+import getpass
+from collections.abc import Callable, Generator
+from typing import cast
+
+from invoke.collection import Collection
+from invoke.context import Context
+from invoke.tasks import Task, task
+
+import fogies.aws_access_key as aws_access_key
+from fogies.tools.aws_environ import (
+    AwsEnvironContextManager,
+    AwsProfile,
+    aws_environ_from_profile,
+)
+from fogies.typing import boto_client_sts
+
+# A factory rather than a pre-built context manager: get_collection() shares
+# this across five tasks, and a context manager built by @contextlib.
+# contextmanager can only be entered once, so each task must build its own
+# fresh instance at run time. Mirrors the _aws_environ_factory() pattern used
+# by consumers of these tasks (see e.g. fogies-infrastructure's tasks/__init__.py).
+AwsEnvironFactory = Callable[[], AwsEnvironContextManager]
+
+
+def _prompt_admin_credentials() -> tuple[str, str]:
+    """Prompt for admin credentials interactively; credentials are never written anywhere."""
+    access_key_id = input("Admin Access Key ID: ").strip()
+    secret_access_key = getpass.getpass("Admin Secret Access Key: ").strip()
+    return access_key_id, secret_access_key
+
+
+@contextlib.contextmanager
+def _resolve_admin_environ(
+    *, aws_environ_factory: AwsEnvironFactory | None, prompt: bool
+) -> Generator[str]:
+    """Enter the configured AWS environment, or prompt for admin credentials.
+
+    Prompts if aws_environ_factory is None, or if prompt is True (e.g. to use
+    different/elevated credentials for a single run). Prompted credentials
+    are never written anywhere. Yields the active access key ID.
+    """
+    if aws_environ_factory is not None and not prompt:
+        with aws_environ_factory() as env:
+            yield env.aws_access_key_id
+        return
+
+    access_key_id, secret_access_key = _prompt_admin_credentials()
+    profile = AwsProfile(
+        name="prompt-admin",
+        aws_access_key_id=access_key_id,
+        aws_secret_access_key=secret_access_key,
+    )
+    # try/except wraps only entering the context manager (where validation
+    # happens), not the yield below — catching ValueError around the yield
+    # too would risk mis-catching an unrelated error raised by the task body.
+    with contextlib.ExitStack() as stack:
+        try:
+            env = stack.enter_context(
+                aws_environ_from_profile(profile=profile, raise_if_exists=False)
+            )
+        except ValueError as exc:
+            raise SystemExit(str(exc)) from exc
+        yield env.aws_access_key_id
+
+
+def _caller_username() -> str:
+    """Return the IAM username that owns the active credentials, via STS."""
+    arn = boto_client_sts().get_caller_identity()["Arn"]
+    # ARN format for IAM users: arn:aws:iam::123456789012:user/username
+    return arn.split("/")[-1]
+
+
+def _print_toml_block(*, profile: AwsProfile) -> None:
+    """Print a TOML block suitable for pasting into aws.toml."""
+    print()
+    print("[{}]".format(profile.name))
+    print('aws_access_key_id = "{}"'.format(profile.aws_access_key_id))
+    print('aws_secret_access_key = "{}"'.format(profile.aws_secret_access_key))
+
+
+def _print_user_key_overview(
+    *, username: str, keys: aws_access_key.IamAccessKeys
+) -> None:
+    """Print an IAM user's key overview: current/previous key details, or a no-keys note.
+
+    Shared by `list` (once per user) and `delete-key`'s confirmation prompt
+    (for the one user being acted on), so both show the same information.
+    """
+    print(username)
+    for label, key in (("current", keys.current), ("previous", keys.previous)):
+        if key is None:
+            continue
+        created_str = key.created.strftime("%Y-%m-%d") if key.created else "unknown"
+        last_used_str = key.last_used.strftime("%Y-%m-%d") if key.last_used else "never"
+        print(
+            "  {} {} | {} | created {} | last used {}".format(
+                label, key.key_id, key.status, created_str, last_used_str
+            )
+        )
+    if keys.current is None:
+        print("  (no access keys)")
+
+
+def get_task_create(
+    *, aws_environ_factory: AwsEnvironFactory | None = None
+) -> Task[Callable[..., None]]:
+    @task(name="create")  # pyright: ignore[reportUntypedFunctionDecorator]
+    def task_create(context: Context, *, prompt: bool = False, username: str) -> None:
+        """
+        Create an IAM user and an associated access key.
+
+        Flags:
+          --prompt    Prompt for admin credentials.
+          --username  IAM username.
+        """
+        _ = context
+        with _resolve_admin_environ(
+            aws_environ_factory=aws_environ_factory, prompt=prompt
+        ):
+            new_profile = aws_access_key.create_user(username=username)
+        print("Created IAM user '{}'.".format(username))
+        print("Created access key {}.".format(new_profile.aws_access_key_id))
+        _print_toml_block(profile=new_profile)
+
+    return cast(Task[Callable[..., None]], task_create)
+
+
+def get_task_delete(
+    *, aws_environ_factory: AwsEnvironFactory | None = None
+) -> Task[Callable[..., None]]:
+    @task(name="delete")  # pyright: ignore[reportUntypedFunctionDecorator]
+    def task_delete(context: Context, *, prompt: bool = False, username: str) -> None:
+        """
+        Delete an IAM user with no remaining access keys.
+
+        Flags:
+          --prompt    Prompt for admin credentials.
+          --username  IAM username.
+        """
+        _ = context
+        with _resolve_admin_environ(
+            aws_environ_factory=aws_environ_factory, prompt=prompt
+        ):
+            protected_username = _caller_username()
+            confirm = (
+                input("Delete IAM user '{}'? [y/N] ".format(username)).strip().lower()
+            )
+            if confirm != "y":
+                print("Aborted.")
+                return
+            aws_access_key.delete_user(
+                username=username,
+                protected_usernames={protected_username},
+            )
+        print("Deleted IAM user '{}'.".format(username))
+
+    return cast(Task[Callable[..., None]], task_delete)
+
+
+def get_task_delete_key(
+    *, aws_environ_factory: AwsEnvironFactory | None = None
+) -> Task[Callable[..., None]]:
+    @task(name="delete-key")  # pyright: ignore[reportUntypedFunctionDecorator]
+    def task_delete_key(
+        context: Context, *, prompt: bool = False, username: str
+    ) -> None:
+        """
+        Delete the oldest access key for an IAM user.
+
+        Flags:
+          --prompt    Prompt for admin credentials.
+          --username  IAM username.
+        """
+        _ = context
+        with _resolve_admin_environ(
+            aws_environ_factory=aws_environ_factory, prompt=prompt
+        ) as admin_key_id:
+            keys = aws_access_key.get_keys(username=username)
+            target = keys.previous or keys.current
+            if target is None:
+                raise SystemExit("IAM user '{}' has no access keys.".format(username))
+            key_id = target.key_id
+            _print_user_key_overview(username=username, keys=keys)
+            print()
+            if keys.previous is None:
+                print(
+                    "WARNING: This is the only key. Deleting it will revoke all access."
+                )
+                print()
+            confirm = input("Delete key {}? [y/N] ".format(key_id)).strip().lower()
+            if confirm != "y":
+                print("Aborted.")
+                return
+            aws_access_key.delete_key(
+                username=username,
+                key_id=key_id,
+                protected_key_ids={admin_key_id},
+            )
+        print("Deleted key {}.".format(key_id))
+
+    return cast(Task[Callable[..., None]], task_delete_key)
+
+
+def get_task_list(
+    *, aws_environ_factory: AwsEnvironFactory | None = None
+) -> Task[Callable[..., None]]:
+    @task(name="list")  # pyright: ignore[reportUntypedFunctionDecorator]
+    def task_list(context: Context, *, prompt: bool = False) -> None:
+        """
+        List all IAM users and their access keys.
+
+        Flags:
+          --prompt  Prompt for admin credentials.
+        """
+        _ = context
+        with _resolve_admin_environ(
+            aws_environ_factory=aws_environ_factory, prompt=prompt
+        ):
+            users = aws_access_key.list_users()
+        if not users:
+            print("No IAM users found.")
+            return
+        for index, user in enumerate(users):
+            if index > 0:
+                print()
+            _print_user_key_overview(username=user.username, keys=user.keys)
+
+    return cast(Task[Callable[..., None]], task_list)
+
+
+def get_task_rotate_key(
+    *, aws_environ_factory: AwsEnvironFactory | None = None
+) -> Task[Callable[..., None]]:
+    @task(name="rotate-key")  # pyright: ignore[reportUntypedFunctionDecorator]
+    def task_rotate_key(
+        context: Context, *, prompt: bool = False, username: str
+    ) -> None:
+        """
+        Add a new access key to an existing IAM user.
+
+        Flags:
+          --prompt    Prompt for admin credentials instead of using the configured AWS environment.
+          --username  IAM username to rotate a key for.
+        """
+        _ = context
+        with _resolve_admin_environ(
+            aws_environ_factory=aws_environ_factory, prompt=prompt
+        ) as admin_key_id:
+            keys = aws_access_key.get_keys(username=username)
+            if keys.previous is not None:
+                _print_user_key_overview(username=username, keys=keys)
+                print()
+                confirm = (
+                    input("Delete key {}? [y/N] ".format(keys.previous.key_id))
+                    .strip()
+                    .lower()
+                )
+                if confirm != "y":
+                    print("Aborted.")
+                    return
+            new_profile = aws_access_key.rotate_key(
+                username=username,
+                protected_key_ids={admin_key_id},
+            )
+        print("Created access key {}.".format(new_profile.aws_access_key_id))
+        _print_toml_block(profile=new_profile)
+
+    return cast(Task[Callable[..., None]], task_rotate_key)
+
+
+def get_collection(
+    *, aws_environ_factory: AwsEnvironFactory | None = None
+) -> Collection:
+    """Get a collection of tasks for managing IAM users and access keys."""
+    collection = Collection("access-key")
+    collection.add_task(get_task_create(aws_environ_factory=aws_environ_factory))
+    collection.add_task(get_task_delete(aws_environ_factory=aws_environ_factory))
+    collection.add_task(get_task_delete_key(aws_environ_factory=aws_environ_factory))
+    collection.add_task(get_task_list(aws_environ_factory=aws_environ_factory))
+    collection.add_task(get_task_rotate_key(aws_environ_factory=aws_environ_factory))
+    return collection