lambda-preflight 0.1.0__py3-none-any.whl

lambda_preflight/runtime/harness.py

@@ -0,0 +1,167 @@
+"""The in-process Lambda runtime shim.
+
+``LambdaHarness`` reconstructs the Lambda invocation contract without Docker,
+SAM, or a cloud call: it resolves the handler once (cold start), then on each
+invoke builds a fresh context, applies the Lambda environment, enforces the
+timeout, and serializes errors the way AWS does.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable, Dict, Optional
+
+from .context import LambdaContext
+from .errors import LambdaTimeout, format_exception
+from .loader import build_lambda_environ, lambda_environment, resolve_handler
+
+
+class InvocationResult:
+    """Outcome of a single invocation.
+
+    ``ok`` distinguishes a normal return from an error envelope. On success
+    ``payload`` is the handler's return value; on failure ``error`` holds the
+    AWS-shape envelope (``errorType`` / ``errorMessage`` / ``stackTrace``).
+    """
+
+    def __init__(
+        self,
+        ok: bool,
+        payload: Any = None,
+        error: Optional[Dict[str, Any]] = None,
+        request_id: str = "",
+        cold_start: bool = False,
+    ) -> None:
+        self.ok = ok
+        self.payload = payload
+        self.error = error
+        self.request_id = request_id
+        self.cold_start = cold_start
+
+    def __repr__(self) -> str:  # pragma: no cover - debug convenience
+        state = "ok" if self.ok else "error"
+        return f"<InvocationResult {state} request_id={self.request_id!r}>"
+
+
+def _run_with_timeout(
+    func: Callable, args: tuple, timeout_seconds: float
+) -> Any:
+    """Run ``func`` in a worker thread, raising LambdaTimeout on overrun.
+
+    A thread is used (not a signal) so the harness works off the main thread
+    — inside pytest, web servers, notebooks — where signal-based timeouts
+    cannot be installed. The worker is a daemon: if it overruns we stop
+    waiting and surface the timeout, mirroring how AWS abandons the invoke.
+    """
+    result: Dict[str, Any] = {}
+
+    def target() -> None:
+        try:
+            result["value"] = func(*args)
+        except BaseException as exc:  # noqa: BLE001 - captured for re-raise
+            result["error"] = exc
+
+    worker = threading.Thread(target=target, daemon=True)
+    worker.start()
+    worker.join(timeout_seconds)
+
+    if worker.is_alive():
+        raise LambdaTimeout(
+            f"Task timed out after {timeout_seconds:.2f} seconds"
+        )
+    if "error" in result:
+        raise result["error"]
+    return result.get("value")
+
+
+class LambdaHarness:
+    """Invoke a Lambda handler in-process with AWS-faithful semantics.
+
+    The handler is resolved lazily on first invoke to reproduce cold-start
+    timing, and the imported module is reused across invokes so module-global
+    state (connection pools, caches) behaves as it does in a warm container.
+
+    An optional ``iam`` evaluator, when provided, is exposed to the boto3
+    intercept hook so calls made inside the handler can be authorized against
+    local policy. The harness itself stays runtime-focused; IAM is delegated.
+    """
+
+    def __init__(
+        self,
+        handler_path: str,
+        function_name: str = "local-function",
+        function_version: str = "$LATEST",
+        memory_mb: int = 128,
+        timeout: float = 3.0,
+        region: str = "us-east-1",
+        account_id: str = "000000000000",
+        environment: Optional[Dict[str, str]] = None,
+        iam: Any = None,
+    ) -> None:
+        self.handler_path = handler_path
+        self.function_name = function_name
+        self.function_version = function_version
+        self.memory_mb = memory_mb
+        self.timeout = timeout
+        self.region = region
+        self.account_id = account_id
+        self.user_environment = dict(environment or {})
+        self.iam = iam
+
+        self._handler: Optional[Callable] = None
+        self._has_run = False  # tracks cold vs warm
+
+    def _ensure_handler(self) -> Callable:
+        """Resolve the handler on first use (cold start)."""
+        if self._handler is None:
+            self._handler = resolve_handler(self.handler_path)
+        return self._handler
+
+    def invoke(
+        self, event: Any, client_context: Any = None
+    ) -> InvocationResult:
+        """Invoke the handler with ``event`` and an AWS-faithful context."""
+        is_cold = not self._has_run
+        handler = self._ensure_handler()
+        self._has_run = True
+
+        context = LambdaContext(
+            function_name=self.function_name,
+            function_version=self.function_version,
+            memory_limit_in_mb=self.memory_mb,
+            timeout_seconds=self.timeout,
+            region=self.region,
+            account_id=self.account_id,
+        )
+        if client_context is not None:
+            context.client_context = client_context
+
+        lambda_env = build_lambda_environ(
+            function_name=self.function_name,
+            function_version=self.function_version,
+            memory_limit_in_mb=self.memory_mb,
+            region=self.region,
+            handler_path=self.handler_path,
+            log_group_name=context.log_group_name,
+            log_stream_name=context.log_stream_name,
+        )
+        lambda_env.update(self.user_environment)
+
+        with lambda_environment(lambda_env):
+            try:
+                payload = _run_with_timeout(
+                    handler, (event, context), self.timeout
+                )
+                return InvocationResult(
+                    ok=True,
+                    payload=payload,
+                    request_id=context.aws_request_id,
+                    cold_start=is_cold,
+                )
+            except BaseException as exc:  # noqa: BLE001 - serialized like AWS
+                return InvocationResult(
+                    ok=False,
+                    error=format_exception(exc),
+                    request_id=context.aws_request_id,
+                    cold_start=is_cold,
+                )

lambda_preflight/runtime/loader.py

@@ -0,0 +1,94 @@
+"""Handler resolution and Lambda environment reproduction.
+
+Two responsibilities:
+
+1. Resolve a ``module.function`` handler string the way the AWS runtime does,
+   importing the module (which runs init / cold-start code) and returning the
+   callable.
+2. Inject the environment variables the Lambda runtime sets, so handler code
+   that reads ``os.environ`` sees the same keys it would in AWS.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from contextlib import contextmanager
+from typing import Callable, Dict, Iterator
+
+from .errors import HandlerLoadError
+
+
+def resolve_handler(handler_path: str) -> Callable:
+    """Resolve a ``module.function`` string to a callable.
+
+    ``app.handler`` imports module ``app`` and returns its ``handler``
+    attribute. Dotted modules (``pkg.mod.handler``) are supported: the final
+    segment is the function, everything before it is the module path.
+    """
+    if "." not in handler_path:
+        raise HandlerLoadError(
+            f"Handler '{handler_path}' must be of the form 'module.function'"
+        )
+
+    module_name, _, func_name = handler_path.rpartition(".")
+    try:
+        module = importlib.import_module(module_name)  # runs cold-start init
+    except ImportError as exc:
+        raise HandlerLoadError(
+            f"Unable to import module '{module_name}': {exc}"
+        ) from exc
+
+    try:
+        handler = getattr(module, func_name)
+    except AttributeError as exc:
+        raise HandlerLoadError(
+            f"Module '{module_name}' has no attribute '{func_name}'"
+        ) from exc
+
+    if not callable(handler):
+        raise HandlerLoadError(f"Handler '{handler_path}' is not callable")
+
+    return handler
+
+
+def build_lambda_environ(
+    function_name: str,
+    function_version: str,
+    memory_limit_in_mb: int,
+    region: str,
+    handler_path: str,
+    log_group_name: str,
+    log_stream_name: str,
+) -> Dict[str, str]:
+    """Return the environment variables the Lambda runtime injects."""
+    return {
+        "AWS_LAMBDA_FUNCTION_NAME": function_name,
+        "AWS_LAMBDA_FUNCTION_VERSION": function_version,
+        "AWS_LAMBDA_FUNCTION_MEMORY_SIZE": str(memory_limit_in_mb),
+        "AWS_LAMBDA_LOG_GROUP_NAME": log_group_name,
+        "AWS_LAMBDA_LOG_STREAM_NAME": log_stream_name,
+        "AWS_REGION": region,
+        "AWS_DEFAULT_REGION": region,
+        "AWS_EXECUTION_ENV": "AWS_Lambda_python",
+        "_HANDLER": handler_path,
+        "TZ": "UTC",
+    }
+
+
+@contextmanager
+def lambda_environment(env: Dict[str, str]) -> Iterator[None]:
+    """Temporarily apply Lambda env vars, restoring prior values on exit."""
+    previous: Dict[str, str] = {}
+    missing = object()
+    try:
+        for key, value in env.items():
+            previous[key] = os.environ.get(key, missing)  # type: ignore[assignment]
+            os.environ[key] = value
+        yield
+    finally:
+        for key, prior in previous.items():
+            if prior is missing:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = prior  # type: ignore[arg-type]

lambda_preflight/testing/__init__.py

@@ -0,0 +1,3 @@
+"""Testing helpers and pytest fixtures."""
+
+from .fixtures import *  # noqa: F401,F403  (registers pytest fixtures)

lambda_preflight/testing/fixtures.py

@@ -0,0 +1,43 @@
+"""pytest fixtures for cloud-free Lambda testing.
+
+Importing this module in a ``conftest.py`` (or via the pytest plugin entry
+point) exposes fixtures that make the biggest use case — fast, charge-free
+tests in CI — a one-liner.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+try:
+    import pytest
+except ImportError:  # pragma: no cover - pytest optional at runtime
+    pytest = None  # type: ignore[assignment]
+
+from .. import events as _events
+from ..runtime import LambdaHarness
+
+
+if pytest is not None:
+
+    @pytest.fixture
+    def lambda_harness() -> Callable[..., LambdaHarness]:
+        """Factory fixture: build a harness for a given handler path.
+
+        Example::
+
+            def test_orders(lambda_harness):
+                harness = lambda_harness("app.handler", timeout=5)
+                result = harness.invoke({"hello": "world"})
+                assert result.ok
+        """
+
+        def _factory(handler_path: str, **kwargs: object) -> LambdaHarness:
+            return LambdaHarness(handler_path, **kwargs)  # type: ignore[arg-type]
+
+        return _factory
+
+    @pytest.fixture
+    def lambda_events():
+        """Expose the event builders as a fixture for convenience."""
+        return _events

lambda_preflight-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: lambda-preflight
+Version: 0.1.0
+Summary: Catch AWS Lambda IAM permission errors and event-shape bugs before you deploy — a local pre-flight linter and AWS-faithful runtime. No Docker, no SAM, no invocation charges.
+Project-URL: Homepage, https://github.com/swaranshu-borgaonkar/lambda-preflight
+Project-URL: Issues, https://github.com/swaranshu-borgaonkar/lambda-preflight/issues
+Author: Swar Borgaonkar
+License: MIT
+License-File: LICENSE
+Keywords: aws,iam,lambda,linter,local,mock,preflight,pytest,serverless,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Provides-Extra: aws
+Requires-Dist: boto3>=1.26; extra == 'aws'
+Provides-Extra: dev
+Requires-Dist: boto3>=1.26; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lambda-preflight
+
+**Catch AWS Lambda IAM permission errors and event-shape bugs before you deploy.**
+
+Every "local lambda" tool runs your handler. `lambda-preflight` does something none of them do: it **checks your handler's AWS calls against your execution role's real IAM policies** and fails locally — so you find the missing `s3:PutObject` on your laptop, not in a CloudWatch log after a failed deploy.
+
+No Docker. No SAM CLI. No cloud invocations, so no invocation charges.
+
+```bash
+pip install "lambda-preflight[aws]"
+```
+
+---
+
+## The headline: local IAM linting
+
+Your Lambda runs as an execution *role*. When that role is missing a permission, you normally find out the slow way — deploy, invoke, read the `AccessDenied` in the logs, redeploy. `lambda-preflight` pulls your role's **real** policies once, caches them, and checks every AWS call your handler makes *before* anything leaves your machine.
+
+```python
+from lambda_preflight import pull_role, PolicyEvaluator, intercept_boto3
+from lambda_preflight import LambdaHarness, events
+
+# Pull the execution role's real policies (managed + inline + boundary), cached after first call.
+policies  = pull_role("my-function-exec-role")
+evaluator = PolicyEvaluator(policies, strict=True)
+
+harness = LambdaHarness("app.handler", timeout=30)
+
+# boto3 calls inside the handler are authorized against the real policy — locally.
+with intercept_boto3(evaluator):
+    result = harness.invoke(events.sqs(body={"orderId": 123}))
+    # If app.handler calls s3:PutObject and the role can't → AccessDenied raised here,
+    # with the same reason AWS would give, before you ever deploy.
+```
+
+Three ways to load policies, so it works on a plane or in locked-down accounts:
+
+```python
+from lambda_preflight import pull_role, load_role_policies, PolicySet
+
+pull_role("my-exec-role")                       # 1. live pull  — needs creds + IAM read, caches result
+load_role_policies("my-exec-role")              # 2. offline    — reuse cache, no AWS call, no charge
+PolicySet.from_policy_documents([{"Statement": [...]}])  # 3. BYO JSON — when you can't pull
+```
+
+It models the parts that actually decide real permissions: explicit-deny-wins, implicit deny, wildcard actions, resource matching, permission-boundary intersection, and common condition operators. What it **can't** faithfully evaluate (uncommon condition keys, SCPs, resource-based policies) it **flags** — in `strict=True` mode it raises `CannotEvaluate` rather than returning a false green. It tells you the edge of its own knowledge instead of guessing.
+
+---
+
+## The foundation: an AWS-faithful local runtime
+
+The linter needs something real to run against, so the runtime half is built to match AWS's actual invocation contract — not a stubbed approximation.
+
+### Schema-accurate event fixtures
+
+The #1 cause of "worked locally, broke in AWS" is a test event whose *shape* is wrong. These builders emit payloads matching AWS's real schemas, so what you test is what you'll get. REST (v1) and HTTP (v2) API Gateway differ meaningfully — they're separate on purpose:
+
+```python
+events.api_gateway_v1(method="GET", path="/health")
+events.api_gateway_v2(method="POST", path="/orders", body={"id": 1})
+events.sqs(records=[{"a": 1}, {"b": 2}])        # real batch shape, messageAttributes, md5
+events.sns(message={"x": 1}, subject="hi")
+events.s3(bucket="b", key="k.txt", event_name="ObjectCreated:Put")
+events.eventbridge(detail={"k": "v"}, detail_type="my.type", source="svc")
+events.dynamodb_stream(keys={"id": {"S": "1"}}, event_name="INSERT")
+```
+
+### Faithful invocation semantics
+
+```python
+result = harness.invoke(event)
+result.ok          # success vs. error
+result.payload     # what the handler returned
+result.error       # {errorType, errorMessage, stackTrace} — AWS's exact envelope
+result.cold_start  # models warm-container reuse across invokes
+```
+
+The `context` reproduces real fields (`aws_request_id`, `invoked_function_arn`, log names) and a live `get_remaining_time_in_millis()` countdown. Timeouts are enforced the way AWS enforces them. Lambda's environment variables are injected so handler code that reads them behaves the same.
+
+### pytest, because CI is the point
+
+Fixtures register automatically — fast, cloud-free, zero-charge tests:
+
+```python
+def test_orders(lambda_harness, lambda_events):
+    harness = lambda_harness("app.handler", timeout=5)
+    result = harness.invoke(lambda_events.sqs(body={"order": 42}))
+    assert result.ok
+```
+
+---
+
+## How this differs from other local-lambda tools
+
+Tools like `python-lambda-local` and `local-aws-lambda` are **runners** — they execute your handler against an event dict you supply. That's the commodity half, and it's solved. `lambda-preflight` includes a competent runner too, but its reason to exist is what sits on top:
+
+| | Typical local-lambda tools | lambda-preflight |
+|---|---|---|
+| Run a handler locally | ✅ | ✅ |
+| Schema-accurate event fixtures | ✋ you write the dict | ✅ built-in, v1 ≠ v2 |
+| Faithful context / timeout / cold-start / AWS-shape errors | partial | ✅ |
+| **IAM permission linting against your real role** | ❌ | ✅ **unique** |
+
+---
+
+## Honest scope
+
+This kills the **shape / contract / runtime-semantics / identity-permission** class of "works locally, breaks in AWS" failures — which is most of the day-to-day pain. It does **not**, and a local tool cannot, reproduce cloud-only realities: cold-start latency, live concurrency, account quotas, **SCPs**, and **resource-based policies** (the last two are recorded in `PolicySet.unscoped`, never silently ignored). The IAM layer is a **pre-flight linter, not a parity guarantee**. For final confidence, run against real AWS credentials.
+
+## License
+
+MIT

lambda_preflight-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+lambda_preflight/__init__.py,sha256=FbDt6uVCDxh4MMGSUxXUncu50jSMygcptFopZX35OjQ,1768
+lambda_preflight/events/__init__.py,sha256=vorVEw2hz6exYOni_j92xNvae0kGXng6Vc4KePc6ohM,329
+lambda_preflight/events/builders.py,sha256=mVq0FD9Gi6foLj51dreQGY9BZlkdax81X874piwnonE,9254
+lambda_preflight/iam/__init__.py,sha256=0Gosb7vDCOzyQ26jp74SKcG8DSNEaH9bzfL95YQSOwA,904
+lambda_preflight/iam/conditions.py,sha256=sKM8JR_xbh6AMv_AYf1bEEXWdJPz4hNqVuUA1Rwuge0,4293
+lambda_preflight/iam/evaluator.py,sha256=XVCzT_IMKv29eGB3Yyzw6w9ra5AcEKl36F51meT1RL4,5674
+lambda_preflight/iam/intercept.py,sha256=8JH9F3yqVZqSG_VlWWej8LKuXH1tPPaj1poGZmPvAlo,3309
+lambda_preflight/iam/model.py,sha256=mD6Q-fXRR5n2sQ_3nsrWBTD7IZxDo_VDmNbRJPBUKio,2775
+lambda_preflight/iam/puller.py,sha256=aIBum1h7JmX5fuczvQZnDF5hnVmvP4UlxswKpB78JP0,6436
+lambda_preflight/runtime/__init__.py,sha256=VjnipgnmZdJtDAKWgryY4EQwAAZw0fmCx8ccGcjZ1hY,305
+lambda_preflight/runtime/context.py,sha256=v4YFekSzfmwOC4WtkWROdEnfG5ZO-3pJbee_niAGXlU,2649
+lambda_preflight/runtime/errors.py,sha256=1HnAImw3deXkiWR2ubUX2AZlcrlmXHSaXjOGoLUFD_c,1094
+lambda_preflight/runtime/harness.py,sha256=GDxIbXcoJwpiuyx5UBCCyL-bslJW8xZMznWMqooRcQY,5926
+lambda_preflight/runtime/loader.py,sha256=wj7YSs6OHU76ahScBB_EjTEGF_7PN2tbPFdnfqPISHA,3084
+lambda_preflight/testing/__init__.py,sha256=u54M4Sd3AhNvBWyBez2j9eGolYRT1MDPm0w2kwoXBEk,116
+lambda_preflight/testing/fixtures.py,sha256=OJa40rxmQa7IEZAwLmO7wciGtJeDnRhwFQks8kbRzg0,1245
+lambda_preflight-0.1.0.dist-info/METADATA,sha256=SdaAI9BqE4gItoSQWvW3QGm8o_sS7DBLkhFSHXuV-YQ,7171
+lambda_preflight-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lambda_preflight-0.1.0.dist-info/entry_points.txt,sha256=Wn-5svchMAOdRq1EvqjXbJe9qRhfCOAhG9WUKRcZYag,64
+lambda_preflight-0.1.0.dist-info/licenses/LICENSE,sha256=twrIGE-FkR0x4T1XsB1cD4_vsd_J9vy7uLWiB8XdMsA,1072
+lambda_preflight-0.1.0.dist-info/RECORD,,

lambda_preflight-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lambda_preflight-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+lambda_preflight = lambda_preflight.testing.fixtures

lambda_preflight-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Swar Borgaonkar
+
+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.