wshtlib 0.1.0__tar.gz

wshtlib-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run pytest
+      - run: uv run mypy wshtlib
+      - run: uv run ruff check wshtlib
+
+  publish:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

wshtlib-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.ltc/
+.kiro/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.venv/
+.coverage
+htmlcov/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+QUEUE_STATUS.md
+ltc.toml

wshtlib-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [0.1.0] - 2026-04-12
+
+Initial release.
+
+### Features
+- Structured JSON logging (`get_logger`) with Lambda context and runtime enrichment
+- CloudWatch EMF metrics (`MetricsContext`, `metrics`) with namespace and dimension support
+- Request context propagation via `ContextVar` (`init_context`, `get_context`, `set_user_id`)
+- Lambda handler decorator (`@bootstrap`) with warming event detection and error boundary
+- FastAPI/Starlette middleware for automatic context init and request logging (`WshtlibMiddleware`)
+- AWS Secrets Manager helper (`require_secret`) with cold-start caching
+- Utilities: `require_env`, `require_https_url`

wshtlib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wholeshoot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wshtlib-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: wshtlib
+Version: 0.1.0
+Summary: Shared runtime library for Wholeshoot services
+Project-URL: Homepage, https://github.com/polsen/wshtlib
+Project-URL: Repository, https://github.com/polsen/wshtlib
+Author: Wholeshoot
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27; extra == 'fastapi'

wshtlib-0.1.0/README.md

@@ -0,0 +1,116 @@
+# wshtlib
+
+Lightweight observability library for AWS Lambda and FastAPI. Zero external dependencies.
+
+A focused alternative to [aws-powertools](https://github.com/aws-powertools/powertools-lambda-python) — covers structured logging, CloudWatch metrics (EMF), request context propagation, and Lambda handler boilerplate. Nothing more.
+
+## Install
+
+```bash
+pip install wshtlib
+```
+
+FastAPI/Starlette middleware is optional:
+
+```bash
+pip install wshtlib[fastapi]
+```
+
+## Usage
+
+### Lambda handler
+
+```python
+from wshtlib import bootstrap, get_logger
+
+logger = get_logger("my-service")
+
+@bootstrap
+def handler(event, context):
+    logger.info("invoked", path=event.get("path"))
+    return {"statusCode": 200}
+```
+
+The decorator handles:
+- Warming events (`"source": "lambda-warming"`) — returns 200 early
+- Context init and structured log enrichment
+- Unhandled exceptions — logs error, returns 500
+
+### Structured logging
+
+```python
+from wshtlib import get_logger
+
+logger = get_logger("my-service")
+logger.info("user signed in", user_id="u_123", plan="pro")
+```
+
+Output is JSON to stdout, enriched with `level`, `timestamp`, `service`, `location`, runtime fields, and Lambda context on invocation.
+
+### CloudWatch metrics (EMF)
+
+```python
+from wshtlib.metrics import metrics
+
+metrics.count("OrderPlaced")
+metrics.put("Duration", 142.5, unit="Milliseconds")
+metrics.flush()
+```
+
+`metrics` is a module-level `MetricsContext` instance. For isolated contexts (e.g. per-request), instantiate `MetricsContext()` directly.
+
+Namespace defaults to the `METRICS_NAMESPACE` env var, falling back to `"Wholeshoot"`.
+
+### Request context
+
+```python
+from wshtlib import get_context, set_user_id
+
+set_user_id(claims["sub"])
+ctx = get_context()  # {"trace_id": ..., "correlation_id": ..., "user_id": ...}
+```
+
+Context is stored in a `ContextVar` — safe for concurrent async handlers.
+
+### FastAPI middleware
+
+```python
+from fastapi import FastAPI
+from wshtlib.middleware import WshtlibMiddleware
+
+app = FastAPI()
+app.add_middleware(WshtlibMiddleware)
+```
+
+Initialises request context, logs `method`, `path`, `status`, `duration_ms` per request, and injects `X-Trace-Id` into the response.
+
+### Utilities
+
+```python
+from wshtlib import require_env, require_https_url, require_secret
+
+db_url = require_env("DATABASE_URL")          # raises RuntimeError if missing/empty
+endpoint = require_https_url(require_env("API_URL"))  # raises ValueError if not https
+api_key = require_secret("api/key")           # raises RuntimeError if missing/empty, cached
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `LOG_LEVEL` | `INFO` | Logger level |
+| `METRICS_NAMESPACE` | `Wholeshoot` | CloudWatch namespace |
+| `ENVIRONMENT` | — | Added as a metrics dimension if set |
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run mypy wshtlib
+uv run ruff check wshtlib
+```
+
+## License
+
+MIT

wshtlib-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "wshtlib"
+version = "0.1.0"
+description = "Shared runtime library for Wholeshoot services"
+authors = [{ name = "Wholeshoot" }]
+license = { text = "MIT" }
+requires-python = ">=3.13"
+dependencies = []
+
+[project.optional-dependencies]
+fastapi = ["starlette>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/polsen/wshtlib"
+Repository = "https://github.com/polsen/wshtlib"
+
+[dependency-groups]
+dev = [
+  "pytest",
+  "pytest-cov",
+  "pytest-asyncio",
+  "black",
+  "ruff",
+  "mypy",
+  "starlette>=0.27",
+  "httpx",
+  "boto3-stubs[secretsmanager]",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wshtlib"]
+
+[tool.black]
+line-length = 88
+
+[tool.isort]
+profile = "black"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "DTZ"]
+
+[tool.mypy]
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short -q"
+
+[tool.coverage.report]
+fail_under = 90

wshtlib-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+

wshtlib-0.1.0/tests/conftest.py

@@ -0,0 +1,68 @@
+"""Shared test helpers for wshtlib test suite."""
+
+import json
+import logging
+from io import StringIO
+from unittest.mock import MagicMock
+
+from wshtlib.logger import _Logger
+
+
+def capture_log(log_fn, *args, **kwargs) -> dict:
+    """Invoke a logger method and return the parsed JSON entry.
+
+    log_fn: Bound logger method (e.g., logger.info).
+    *args, **kwargs: Arguments to pass to log_fn.
+    Returns the parsed JSON log entry as a dict.
+    Raises AttributeError if log_fn is not a bound _Logger method.
+    Raises json.JSONDecodeError if the emitted output is not valid JSON.
+    """
+    buf = StringIO()
+    handler = logging.StreamHandler(buf)
+    handler.setFormatter(log_fn.__self__._formatter)
+    log_fn.__self__.handlers = [handler]
+    log_fn(*args, **kwargs)
+    return json.loads(buf.getvalue().strip())
+
+
+def fresh_logger(name: str = "test-svc") -> _Logger:
+    """Create a new _Logger instance, bypassing the registry cache.
+
+    name: Logger name. Defaults to "test-svc".
+    Returns a _Logger with DEBUG level.
+    """
+    lg = _Logger(name)
+    lg.setLevel(logging.DEBUG)
+    return lg
+
+
+def make_lambda_context(**kwargs) -> MagicMock:
+    """Create a mock Lambda context object with specified attributes.
+
+    **kwargs: Attributes to set (function_name, arn, memory, request_id).
+    Returns a MagicMock with Lambda context attributes.
+    """
+    ctx = MagicMock()
+    ctx.function_name = kwargs.get("function_name", "my-lambda")
+    ctx.invoked_function_arn = kwargs.get(
+        "arn", "arn:aws:lambda:us-west-2:123:function:my-lambda"
+    )
+    ctx.memory_limit_in_mb = kwargs.get("memory", "256")
+    ctx.aws_request_id = kwargs.get("request_id", "req-abc-123")
+    return ctx
+
+
+def emit_with_lambda_context(ctx: MagicMock) -> dict:
+    """Log a message with Lambda context set and return the parsed JSON entry.
+
+    ctx: Lambda context object.
+    Returns the parsed JSON log entry as a dict.
+    """
+    lg = fresh_logger("lambda-svc")
+    lg.set_lambda_context(ctx)
+    buf = StringIO()
+    handler = logging.StreamHandler(buf)
+    handler.setFormatter(lg._formatter)
+    lg.handlers = [handler]
+    lg.info("lambda log")
+    return json.loads(buf.getvalue().strip())

wshtlib-0.1.0/tests/test_context.py

@@ -0,0 +1,170 @@
+"""Test request-scoped context store."""
+
+from unittest.mock import MagicMock
+
+from wshtlib.context import (
+    clear_context,
+    get_context,
+    init_context,
+    init_context_from_request,
+    set_user_id,
+)
+
+
+def setup_function() -> None:
+    clear_context()
+
+
+# --- init_context ---
+
+
+def test_init_context_trace_id_from_header() -> None:
+    event = {"headers": {"x-amzn-trace-id": "Root=1-abc"}}
+    lctx = MagicMock(aws_request_id="req-123")
+    init_context(event, lctx)
+    c = get_context()
+    assert c["trace_id"] == "Root=1-abc"
+    assert c["correlation_id"] == "req-123"
+    assert c["user_id"] is None
+
+
+def test_init_context_trace_id_from_request_context() -> None:
+    event = {"requestContext": {"requestId": "apigw-req-id"}}
+    lctx = MagicMock(aws_request_id="req-456")
+    init_context(event, lctx)
+    c = get_context()
+    assert c["trace_id"] == "apigw-req-id"
+
+
+def test_init_context_header_takes_precedence_over_request_context() -> None:
+    event = {
+        "headers": {"x-amzn-trace-id": "Root=1-header"},
+        "requestContext": {"requestId": "apigw-id"},
+    }
+    lctx = MagicMock(aws_request_id="req-789")
+    init_context(event, lctx)
+    assert get_context()["trace_id"] == "Root=1-header"
+
+
+def test_init_context_no_trace_id() -> None:
+    init_context({}, MagicMock(aws_request_id="req-000"))
+    assert get_context()["trace_id"] is None
+
+
+def test_init_context_null_headers() -> None:
+    event = {"headers": None}
+    init_context(event, MagicMock(aws_request_id="req-null"))
+    assert get_context()["trace_id"] is None
+
+
+def test_init_context_no_aws_request_id() -> None:
+    lctx = object()  # no aws_request_id attribute
+    init_context({}, lctx)
+    assert get_context()["correlation_id"] is None
+
+
+# --- init_context_from_request ---
+
+
+def _make_request(headers: dict, path: str = "/test") -> MagicMock:
+    req = MagicMock()
+    req.headers = headers
+    req.scope = {"path": path}
+    return req
+
+
+def test_init_context_from_request_trace_id() -> None:
+    req = _make_request({"x-amzn-trace-id": "Root=1-req", "x-correlation-id": "corr-1"})
+    init_context_from_request(req)
+    c = get_context()
+    assert c["trace_id"] == "Root=1-req"
+    assert c["correlation_id"] == "corr-1"
+    assert c["user_id"] is None
+
+
+def test_init_context_from_request_correlation_id_fallback_to_path() -> None:
+    req = _make_request({"x-amzn-trace-id": "Root=1-x"}, path="/shoots/abc")
+    init_context_from_request(req)
+    assert get_context()["correlation_id"] == "/shoots/abc"
+
+
+def test_init_context_from_request_no_trace_id() -> None:
+    req = _make_request({})
+    init_context_from_request(req)
+    assert get_context()["trace_id"] is None
+
+
+# --- get_context returns a copy ---
+
+
+def test_get_context_returns_copy() -> None:
+    init_context({}, MagicMock(aws_request_id="r"))
+    c1 = get_context()
+    c1["injected"] = True
+    assert "injected" not in get_context()
+
+
+# --- set_user_id ---
+
+
+def test_set_user_id() -> None:
+    init_context({}, MagicMock(aws_request_id="r"))
+    set_user_id("user-sub-abc")
+    assert get_context()["user_id"] == "user-sub-abc"
+
+
+def test_set_user_id_none() -> None:
+    init_context({}, MagicMock(aws_request_id="r"))
+    set_user_id("user-sub-abc")
+    set_user_id(None)
+    assert get_context()["user_id"] is None
+
+
+def test_set_user_id_preserves_other_fields() -> None:
+    init_context(
+        {"headers": {"x-amzn-trace-id": "Root=1-keep"}},
+        MagicMock(aws_request_id="r"),
+    )
+    set_user_id("u")
+    c = get_context()
+    assert c["trace_id"] == "Root=1-keep"
+    assert c["user_id"] == "u"
+
+
+# --- clear_context ---
+
+
+def test_clear_context() -> None:
+    init_context({}, MagicMock(aws_request_id="r"))
+    clear_context()
+    assert get_context() == {}
+
+
+# --- context isolation between coroutines ---
+
+
+def test_context_isolation_between_tasks() -> None:
+    """Each asyncio task gets its own context copy via contextvars."""
+    import asyncio
+
+    async def task_a():
+        init_context(
+            {"headers": {"x-amzn-trace-id": "A"}}, MagicMock(aws_request_id="a")
+        )
+        await asyncio.sleep(0)
+        return get_context()["trace_id"]
+
+    async def task_b():
+        init_context(
+            {"headers": {"x-amzn-trace-id": "B"}}, MagicMock(aws_request_id="b")
+        )
+        await asyncio.sleep(0)
+        return get_context()["trace_id"]
+
+    async def run():
+        results = await asyncio.gather(task_a(), task_b())
+        return results
+
+    a, b = asyncio.run(run())
+    assert a == "A"
+    assert b == "B"

wshtlib-0.1.0/tests/test_decorators.py

@@ -0,0 +1,165 @@
+"""Test Lambda handler decorator."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from wshtlib.context import clear_context, get_context
+from wshtlib.decorators import bootstrap
+
+
+@pytest.fixture(autouse=True)
+def reset_context() -> None:
+    clear_context()
+    yield
+    clear_context()
+
+
+def _make_lambda_context(request_id: str = "req-test") -> MagicMock:
+    ctx = MagicMock()
+    ctx.aws_request_id = request_id
+    return ctx
+
+
+# --- warming events ---
+
+
+def test_warming_event_returns_200() -> None:
+    @bootstrap
+    def handler(event, context):
+        raise AssertionError("should not be called")
+
+    result = handler({"source": "lambda-warming"}, _make_lambda_context())
+    assert result == {"statusCode": 200}
+
+
+def test_warming_event_skips_context_init() -> None:
+    @bootstrap
+    def handler(event, context):
+        pass  # pragma: no cover
+
+    handler({"source": "lambda-warming"}, _make_lambda_context("req-warm"))
+    assert get_context() == {}
+
+
+def test_non_warming_source_does_not_short_circuit() -> None:
+    called = []
+
+    @bootstrap
+    def handler(event, context):
+        called.append(True)
+        return {"statusCode": 200}
+
+    handler({"source": "other"}, _make_lambda_context())
+    assert called == [True]
+
+
+# --- context initialisation ---
+
+
+def test_init_context_called_before_handler() -> None:
+    captured = {}
+
+    @bootstrap
+    def handler(event, context):
+        captured.update(get_context())
+        return {}
+
+    event = {"headers": {"x-amzn-trace-id": "Root=1-abc"}}
+    handler(event, _make_lambda_context("req-ctx"))
+    assert captured["trace_id"] == "Root=1-abc"
+    assert captured["correlation_id"] == "req-ctx"
+
+
+def test_set_lambda_context_called() -> None:
+    with patch("wshtlib.decorators.set_lambda_context") as mock_set:
+
+        @bootstrap
+        def handler(event, context):
+            return {}
+
+        lctx = _make_lambda_context()
+        handler({}, lctx)
+        mock_set.assert_called_once_with(lctx)
+
+
+# --- error handling ---
+
+
+def test_unhandled_exception_returns_500() -> None:
+    @bootstrap
+    def handler(event, context):
+        raise ValueError("boom")
+
+    result = handler({}, _make_lambda_context())
+    assert result == {"statusCode": 500}
+
+
+def test_unhandled_exception_logs_error() -> None:
+    with patch("wshtlib.decorators.logger") as mock_logger:
+
+        @bootstrap
+        def handler(event, context):
+            raise RuntimeError("oops")
+
+        handler({}, _make_lambda_context())
+        mock_logger.error.assert_called_once()
+        call_args = mock_logger.error.call_args[0]
+        assert call_args[1] == "handler"
+
+
+def test_successful_return_value_passed_through() -> None:
+    @bootstrap
+    def handler(event, context):
+        return {"statusCode": 201, "body": "ok"}
+
+    result = handler({}, _make_lambda_context())
+    assert result == {"statusCode": 201, "body": "ok"}
+
+
+# --- functools.wraps ---
+
+
+def test_decorator_preserves_function_name() -> None:
+    @bootstrap
+    def my_special_handler(event, context):
+        return {}
+
+    assert my_special_handler.__name__ == "my_special_handler"
+
+
+def test_decorator_preserves_docstring() -> None:
+    @bootstrap
+    def handler(event, context):
+        """My handler docstring."""
+        return {}
+
+    assert handler.__doc__ == "My handler docstring."
+
+
+# --- public API ---
+
+
+def test_bootstrap_exported_from_wshtlib() -> None:
+    import wshtlib
+
+    assert hasattr(wshtlib, "bootstrap")
+    assert callable(wshtlib.bootstrap)
+
+
+def test_lambda_handler_not_exported_from_wshtlib() -> None:
+    import wshtlib
+
+    assert not hasattr(wshtlib, "lambda_handler")
+
+
+def test_bootstrap_in_all() -> None:
+    import wshtlib
+
+    assert "bootstrap" in wshtlib.__all__
+
+
+def test_lambda_handler_not_in_all() -> None:
+    import wshtlib
+
+    assert "lambda_handler" not in wshtlib.__all__

wshtlib-0.1.0/tests/test_env.py

@@ -0,0 +1,22 @@
+"""Tests for wshtlib.env"""
+
+import pytest
+
+from wshtlib.env import require_env
+
+
+def test_require_env_returns_value(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MY_VAR", "hello")
+    assert require_env("MY_VAR") == "hello"
+
+
+def test_require_env_raises_when_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MY_VAR", raising=False)
+    with pytest.raises(RuntimeError, match="MY_VAR"):
+        require_env("MY_VAR")
+
+
+def test_require_env_raises_when_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MY_VAR", "")
+    with pytest.raises(RuntimeError, match="MY_VAR"):
+        require_env("MY_VAR")