repro-lambda 0.6.1__tar.gz → 0.7.1__tar.gz

repro_lambda-0.7.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.7.1"
+}

{repro_lambda-0.6.1 → repro_lambda-0.7.1}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.7.1](https://github.com/antonbabenko/repro-lambda/compare/v0.7.0...v0.7.1) (2026-06-23)
+
+
+### Documentation
+
+* split SETUP into SETUP+USAGE, add runnable terraform example, restructure README ([#11](https://github.com/antonbabenko/repro-lambda/issues/11)) ([768ebda](https://github.com/antonbabenko/repro-lambda/commit/768ebda07aefa51cc15c0a5b52adbd251b7891d2))
+
+## [0.7.0](https://github.com/antonbabenko/repro-lambda/compare/v0.6.1...v0.7.0) (2026-06-23)
+
+
+### Features
+
+* support the python3.14 lambda runtime ([#9](https://github.com/antonbabenko/repro-lambda/issues/9)) ([c3fcd8c](https://github.com/antonbabenko/repro-lambda/commit/c3fcd8ceb400891e152293ba06ada747aaa21f9f))
+
 ## [0.6.1](https://github.com/antonbabenko/repro-lambda/compare/v0.6.0...v0.6.1) (2026-06-22)
 
 

repro_lambda-0.7.1/LICENSE

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

repro_lambda-0.7.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: repro-lambda
+Version: 0.7.1
+Summary: Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf.
+Project-URL: Homepage, https://github.com/antonbabenko/repro-lambda
+Project-URL: Repository, https://github.com/antonbabenko/repro-lambda
+Project-URL: Issues, https://github.com/antonbabenko/repro-lambda/issues
+Author-email: Anton Babenko <anton@antonbabenko.com>
+License: MIT
+License-File: LICENSE
+Keywords: aws,lambda,reproducible-builds,serverless,terraform
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.34
+Requires-Dist: repro-zipfile>=0.3.1
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: moto[s3]>=5; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# repro-lambda
+
+Build reproducible AWS Lambda packages outside Terraform, optimized for
+[terraform-aws-lambda](https://registry.terraform.io/modules/terraform-aws-modules/lambda/aws/latest) by [serverless.tf](https://serverless.tf/).
+
+Produces byte-identical zip files across local dev (macOS) and CI (Linux),
+uploads to S3 by content-hash key, and lets Terraform read `s3_existing_package`
+instead of building during `terraform plan`/`apply`.
+
+## Install
+
+    pip install repro-lambda
+
+## Quick start
+
+    repro-lambda lock                     # regenerate per-arch requirement + source locks
+    repro-lambda build --bucket <bucket>  # build all lambdas in lambdas.toml, upload to S3
+    repro-lambda build --verify --dry-run # two-pass byte-reproducibility check (no upload)
+    repro-lambda promote \
+      --dev-bucket <dev> --prod-bucket <prod>  # copy dev -> prod by content sha (no rebuild)
+
+`--bucket` (or `REPRO_LAMBDA_BUCKET`) is required for a real build; add
+`--dry-run` to build without uploading. There is no `init` command yet (the
+subcommand is currently a stub).
+
+## Documentation
+
+What each document covers, by section:
+
+### Setup - one-time AWS provisioning ([SETUP.md](./SETUP.md))
+
+Provision the supporting infrastructure once per AWS account and environment.
+
+- [Architecture](./SETUP.md#architecture) - artifact buckets, key-level immutability, the content-hash model
+- [Terraform - per-account bootstrap](./SETUP.md#terraform---per-account-bootstrap) - the buckets, the GitHub OIDC builder role, and outputs
+- [GitHub OIDC provider](./SETUP.md#github-oidc-provider) - declaring the shared per-account OIDC provider
+- [Next steps](./SETUP.md#next-steps) - where to go after provisioning
+
+### Usage - day-to-day ([USAGE.md](./USAGE.md))
+
+Using `repro-lambda` once the infrastructure exists.
+
+- [Source-repo CI workflow](./USAGE.md#source-repo-ci-workflow) - wiring the reusable build workflow into CI/CD
+- [Per-Lambda manifest](./USAGE.md#per-lambda-manifest) - the `lambdas.toml` fields
+  - [Per-lambda builder overrides](./USAGE.md#per-lambda-builder-overrides) - per-lambda base image and file filters
+- [Declarative sources](./USAGE.md#declarative-sources---lambdasource) - pinned external artifacts via `[[lambda.source]]`
+- [Terraform consumer (`s3_existing_package`)](./USAGE.md#terraform-consumer---s3_existing_package) - wiring `terraform-aws-modules/lambda/aws` to the built artifact
+- [Smoke test](./USAGE.md#smoke-test) - first-build verification and the clean migration plan diff
+- [Troubleshooting](./USAGE.md#troubleshooting) - upload 403s, `PreconditionFailed`, noisy plans
+- [Node.js (npm) Lambdas](./USAGE.md#nodejs-npm-lambdas) - npm packaging support
+  - [Manifest fields for npm specs](./USAGE.md#manifest-fields-for-npm-specs)
+  - [Lockfile regeneration](./USAGE.md#lockfile-regeneration)
+- [Lambda@Edge example](./USAGE.md#lambdaedge-example) - `us-east-1` artifacts for CloudFront
+- [Caveats](./USAGE.md#caveats) - npm workspaces, native deps, symlinks
+
+### Example - runnable ([examples/complete/](./examples/complete/))
+
+A self-contained consumer setup: manifest, catalog, and Terraform using
+`terraform-aws-modules/lambda/aws`.
+
+- [What this example shows](./examples/complete/README.md#what-this-example-shows) - files and layout
+- [The build-outside-Terraform flow](./examples/complete/README.md#the-build-outside-terraform-flow) - build, inspect the catalog, apply
+- [Expected plan diff](./examples/complete/README.md#expected-plan-diff) - the `s3_key`-only diff to expect
+
+## License
+
+MIT - see [LICENSE](./LICENSE).
+
+## Author
+
+Anton Babenko - [@antonbabenko](https://twitter.com/antonbabenko) on Twitter, [antonbabenko](https://www.linkedin.com/in/antonbabenko/) on LinkedIn.

repro_lambda-0.7.1/README.md

@@ -0,0 +1,71 @@
+# repro-lambda
+
+Build reproducible AWS Lambda packages outside Terraform, optimized for
+[terraform-aws-lambda](https://registry.terraform.io/modules/terraform-aws-modules/lambda/aws/latest) by [serverless.tf](https://serverless.tf/).
+
+Produces byte-identical zip files across local dev (macOS) and CI (Linux),
+uploads to S3 by content-hash key, and lets Terraform read `s3_existing_package`
+instead of building during `terraform plan`/`apply`.
+
+## Install
+
+    pip install repro-lambda
+
+## Quick start
+
+    repro-lambda lock                     # regenerate per-arch requirement + source locks
+    repro-lambda build --bucket <bucket>  # build all lambdas in lambdas.toml, upload to S3
+    repro-lambda build --verify --dry-run # two-pass byte-reproducibility check (no upload)
+    repro-lambda promote \
+      --dev-bucket <dev> --prod-bucket <prod>  # copy dev -> prod by content sha (no rebuild)
+
+`--bucket` (or `REPRO_LAMBDA_BUCKET`) is required for a real build; add
+`--dry-run` to build without uploading. There is no `init` command yet (the
+subcommand is currently a stub).
+
+## Documentation
+
+What each document covers, by section:
+
+### Setup - one-time AWS provisioning ([SETUP.md](./SETUP.md))
+
+Provision the supporting infrastructure once per AWS account and environment.
+
+- [Architecture](./SETUP.md#architecture) - artifact buckets, key-level immutability, the content-hash model
+- [Terraform - per-account bootstrap](./SETUP.md#terraform---per-account-bootstrap) - the buckets, the GitHub OIDC builder role, and outputs
+- [GitHub OIDC provider](./SETUP.md#github-oidc-provider) - declaring the shared per-account OIDC provider
+- [Next steps](./SETUP.md#next-steps) - where to go after provisioning
+
+### Usage - day-to-day ([USAGE.md](./USAGE.md))
+
+Using `repro-lambda` once the infrastructure exists.
+
+- [Source-repo CI workflow](./USAGE.md#source-repo-ci-workflow) - wiring the reusable build workflow into CI/CD
+- [Per-Lambda manifest](./USAGE.md#per-lambda-manifest) - the `lambdas.toml` fields
+  - [Per-lambda builder overrides](./USAGE.md#per-lambda-builder-overrides) - per-lambda base image and file filters
+- [Declarative sources](./USAGE.md#declarative-sources---lambdasource) - pinned external artifacts via `[[lambda.source]]`
+- [Terraform consumer (`s3_existing_package`)](./USAGE.md#terraform-consumer---s3_existing_package) - wiring `terraform-aws-modules/lambda/aws` to the built artifact
+- [Smoke test](./USAGE.md#smoke-test) - first-build verification and the clean migration plan diff
+- [Troubleshooting](./USAGE.md#troubleshooting) - upload 403s, `PreconditionFailed`, noisy plans
+- [Node.js (npm) Lambdas](./USAGE.md#nodejs-npm-lambdas) - npm packaging support
+  - [Manifest fields for npm specs](./USAGE.md#manifest-fields-for-npm-specs)
+  - [Lockfile regeneration](./USAGE.md#lockfile-regeneration)
+- [Lambda@Edge example](./USAGE.md#lambdaedge-example) - `us-east-1` artifacts for CloudFront
+- [Caveats](./USAGE.md#caveats) - npm workspaces, native deps, symlinks
+
+### Example - runnable ([examples/complete/](./examples/complete/))
+
+A self-contained consumer setup: manifest, catalog, and Terraform using
+`terraform-aws-modules/lambda/aws`.
+
+- [What this example shows](./examples/complete/README.md#what-this-example-shows) - files and layout
+- [The build-outside-Terraform flow](./examples/complete/README.md#the-build-outside-terraform-flow) - build, inspect the catalog, apply
+- [Expected plan diff](./examples/complete/README.md#expected-plan-diff) - the `s3_key`-only diff to expect
+
+## License
+
+MIT - see [LICENSE](./LICENSE).
+
+## Author
+
+Anton Babenko - [@antonbabenko](https://twitter.com/antonbabenko) on Twitter, [antonbabenko](https://www.linkedin.com/in/antonbabenko/) on LinkedIn.

repro_lambda-0.7.1/SETUP.md

@@ -0,0 +1,262 @@
+# Setting up `repro-lambda` for your project
+
+`repro-lambda` builds and uploads Lambda artifacts to S3 outside of Terraform.
+This guide covers the one-time job: provisioning the supporting AWS
+infrastructure (the artifact buckets plus the GitHub OIDC builder role) once per
+AWS account and region, so that Terraform can later read those artifacts via
+`s3_existing_package`.
+
+This is a copy-paste-able reference. Adapt the names and account IDs to your
+environment. Once the infrastructure exists, see [USAGE.md](./USAGE.md) for
+day-to-day use (the CI workflow, the per-Lambda manifest, and consuming
+artifacts from Terraform).
+
+## Architecture
+
+For each environment (e.g. `dev`, `prod`) you typically need:
+
+```
+${env}-my-lambda-artifacts            S3 bucket, region = eu-west-1 (or your primary region)
+${env}-my-lambda-artifacts-us-east-1  S3 bucket, region = us-east-1 (for Lambda@Edge - optional)
+
+gha-lambda-builder-${env}             IAM role, assumed via GitHub OIDC by source-repo CI to upload
+```
+
+Both buckets enforce **key-level immutability** via bucket policy:
+
+- `s3:PutObject` denied unless `If-None-Match=*` is set (writes are first-write-wins)
+- `s3:DeleteObject` and `s3:DeleteObjectVersion` denied
+- The Lambda service is allowed `s3:GetObject` so functions can load their zip
+
+Once an artifact with a content-hash key (`lambdas/<name>/<sha256>.zip`) is
+uploaded, the key is permanently bound to those bytes. `repro-lambda` treats
+HTTP 412 PreconditionFailed on a duplicate upload as success.
+
+## Terraform - per-account bootstrap
+
+The Terraform below assumes you already have a configured AWS provider in the
+target account. Drop it into your bootstrap directory (or anywhere you provision
+account-wide infrastructure that has no dependencies on other Terraform state).
+
+```hcl
+# us-east-1 is needed only for Lambda@Edge artifacts. Skip if you don't use L@E.
+provider "aws" {
+  alias  = "us_east_1"
+  region = "us-east-1"
+}
+
+locals {
+  env                     = "dev" # change per environment
+  lambda_artifacts_bucket_primary  = "${local.env}-my-lambda-artifacts"
+  lambda_artifacts_bucket_us_east_1 = "${local.env}-my-lambda-artifacts-us-east-1"
+
+  # GitHub OIDC subjects allowed to assume the builder role.
+  # Pattern: repo:<owner>/<repo>:* - narrow to specific refs in production.
+  lambda_builder_oidc_subjects = [
+    "repo:my-org/my-source-repo:*",
+  ]
+}
+
+# Immutability policy applied to every artifact bucket.
+data "aws_iam_policy_document" "lambda_artifacts_immutability" {
+  for_each = toset([
+    local.lambda_artifacts_bucket_primary,
+    local.lambda_artifacts_bucket_us_east_1,
+  ])
+
+  statement {
+    sid    = "DenyOverwrites"
+    effect = "Deny"
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+
+    actions   = ["s3:PutObject"]
+    resources = ["arn:aws:s3:::${each.value}/*"]
+
+    condition {
+      test     = "StringNotEquals"
+      variable = "s3:If-None-Match"
+      values   = ["*"]
+    }
+  }
+
+  statement {
+    sid    = "DenyDelete"
+    effect = "Deny"
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+
+    actions = [
+      "s3:DeleteObject",
+      "s3:DeleteObjectVersion",
+    ]
+    resources = ["arn:aws:s3:::${each.value}/*"]
+  }
+
+  statement {
+    sid    = "AllowLambdaServiceRead"
+    effect = "Allow"
+
+    principals {
+      type        = "Service"
+      identifiers = ["lambda.amazonaws.com"]
+    }
+
+    actions   = ["s3:GetObject"]
+    resources = ["arn:aws:s3:::${each.value}/*"]
+
+    condition {
+      test     = "StringEquals"
+      variable = "aws:SourceAccount"
+      values   = [data.aws_caller_identity.current.account_id]
+    }
+  }
+}
+
+data "aws_caller_identity" "current" {}
+
+# Primary-region bucket
+module "lambda_artifacts_bucket_primary" {
+  source  = "terraform-aws-modules/s3-bucket/aws"
+  version = "~> 4.0"
+
+  bucket = local.lambda_artifacts_bucket_primary
+
+  versioning = {
+    enabled = false # sha-as-key IS the versioning
+  }
+
+  server_side_encryption_configuration = {
+    rule = {
+      apply_server_side_encryption_by_default = {
+        sse_algorithm = "AES256"
+      }
+    }
+  }
+
+  attach_policy = true
+  policy        = data.aws_iam_policy_document.lambda_artifacts_immutability[local.lambda_artifacts_bucket_primary].json
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+
+  force_destroy = false
+}
+
+# us-east-1 bucket - only needed for Lambda@Edge. Remove if not using L@E.
+module "lambda_artifacts_bucket_us_east_1" {
+  source  = "terraform-aws-modules/s3-bucket/aws"
+  version = "~> 4.0"
+
+  providers = {
+    aws = aws.us_east_1
+  }
+
+  bucket = local.lambda_artifacts_bucket_us_east_1
+
+  versioning = {
+    enabled = false
+  }
+
+  server_side_encryption_configuration = {
+    rule = {
+      apply_server_side_encryption_by_default = {
+        sse_algorithm = "AES256"
+      }
+    }
+  }
+
+  attach_policy = true
+  policy        = data.aws_iam_policy_document.lambda_artifacts_immutability[local.lambda_artifacts_bucket_us_east_1].json
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+
+  force_destroy = false
+}
+
+# OIDC role assumed by GitHub Actions in source repos to upload artifacts.
+module "gha_lambda_builder_role" {
+  source  = "terraform-aws-modules/iam/aws//modules/iam-role"
+  version = "~> 6.0"
+
+  name = "gha-lambda-builder-${local.env}"
+
+  enable_github_oidc     = true
+  oidc_wildcard_subjects = local.lambda_builder_oidc_subjects
+
+  create_inline_policy = true
+  inline_policy_permissions = {
+    WriteLambdaArtifacts = {
+      actions = [
+        "s3:PutObject",
+        "s3:GetObject",
+        "s3:HeadObject",
+        "s3:ListBucket",
+      ]
+      resources = [
+        module.lambda_artifacts_bucket_primary.s3_bucket_arn,
+        "${module.lambda_artifacts_bucket_primary.s3_bucket_arn}/*",
+        module.lambda_artifacts_bucket_us_east_1.s3_bucket_arn,
+        "${module.lambda_artifacts_bucket_us_east_1.s3_bucket_arn}/*",
+      ]
+    }
+  }
+}
+
+output "lambda_artifacts_bucket_primary_arn" {
+  value = module.lambda_artifacts_bucket_primary.s3_bucket_arn
+}
+
+output "lambda_artifacts_bucket_us_east_1_arn" {
+  value = module.lambda_artifacts_bucket_us_east_1.s3_bucket_arn
+}
+
+output "gha_lambda_builder_role_arn" {
+  value = module.gha_lambda_builder_role.arn
+}
+```
+
+> Note: if you only use a single region (no Lambda@Edge), remove every
+> us-east-1 reference together, or `terraform plan` fails on dangling
+> references: the `lambda_artifacts_bucket_us_east_1` module, the `us_east_1`
+> provider alias, the `local.lambda_artifacts_bucket_us_east_1` entry in the
+> immutability policy `for_each`, and the two
+> `module.lambda_artifacts_bucket_us_east_1` ARNs in the OIDC role's
+> `WriteLambdaArtifacts` resources.
+
+Apply the Terraform once per environment. The bucket names and role ARN are
+referenced by your source repos' CI workflows in [USAGE.md](./USAGE.md).
+
+## GitHub OIDC provider
+
+If your account doesn't already have the GitHub Actions OIDC provider, the
+`terraform-aws-modules/iam` collection includes a module for it:
+
+```hcl
+module "iam_github_oidc_provider" {
+  source  = "terraform-aws-modules/iam/aws//modules/iam-oidc-provider"
+  version = "~> 6.0"
+}
+```
+
+The provider is shared per AWS account - declare it once, not per environment.
+
+## Next steps
+
+The AWS infrastructure is now provisioned. To use it day-to-day:
+
+- [USAGE.md](./USAGE.md) - the source-repo CI workflow, the per-Lambda manifest,
+  declarative sources, consuming artifacts from Terraform, and troubleshooting.
+- [examples/complete/](./examples/complete/) - a runnable example that wires the
+  pieces together.