eai-core-infra

Python package to manage core Pulumi infrastructure resources for ExtensibilityAI-provided deployments.

Install

From PyPI:

pip install eai-core-infra
# or
uv add eai-core-infra

2.0 is a breaking release (no deprecation shims). Pin eai-core-infra<2 until you migrate; see docs/MIGRATION-2.0.md.

Database pooler (PgBouncer)

Opt-in per app stack with <cloud>.db.pooler. Absent or enabled: false changes nothing. An app owns a pooler in its namespace:

cloud:
  db:
    flags: {max_connections: "100"}   # optional; enables the connection-budget check
    pooler:
      enabled: true
      replicas: 2                      # fixed; never autoscaled
      defaultPoolSize: 4               # pool for DATABASE_NAME
      pools: {api: 8, workers: 24}     # named pools: DATABASE_POOL_<NAME>=<db>__<name>
      clients:                         # other apps' DB users allowed through
        - {user: my-consumer, namespace: my-consumer, maxConnections: 6}

Or it is a client of another app's pooler:

cloud:
  db:
    pooler: {enabled: true, namespace: owner-app, pool: workers}

• Server connections: replicas × (Σ pool sizes + reservePoolSize per pool + Σ client maxConnections). With db.flags.max_connections, parsing checks that this, plus directReserve and 3 superuser connections, fits.

• Transaction mode (the default) doesn't support session state across transactions:

  • no session SET (use SET LOCAL);
  • no session advisory locks (use pg_advisory_xact_lock);
  • no LISTEN/NOTIFY and no WITH HOLD cursors.

  Protocol-level prepared statements work (maxPreparedStatements). Don't hold a transaction open across slow work.

• Migrations and admin connect directly, through DATABASE_DIRECT_HOST and DATABASE_DIRECT_PORT.

The infra library that owns the stack (e.g. eai-web-app-infra) calls create_pgbouncer and writes the app-env keys.

Bucket options (GCP)

cloud.bucket (or each cloud.buckets.create[] entry) takes optional cors, autoclass and lifecycleRules on GCP (2.9.0+). Unset, the bucket renders exactly as before. AWS buckets reject these keys.

cloud:
  bucket:
    enabled: true
    retentionDays: 30                  # optional; bucket retention policy
    cors:                              # e.g. browser PUTs to signed URLs
      - origins: [https://app.example.com]
        methods: [GET, PUT, HEAD]      # case-insensitive
        responseHeaders: [Content-Type, ETag]
        maxAgeSeconds: 3600            # default
    autoclass:
      enabled: true                    # default; needs storageClass STANDARD (default)
      terminalStorageClass: ARCHIVE    # NEARLINE | ARCHIVE; unset = GCS default (NEARLINE)
    lifecycleRules:
      - action: {type: AbortIncompleteMultipartUpload}
        condition: {age: 7}
      - action: {type: Delete}
        condition: {matchesPrefixes: [tmp/], age: 1}
      - action: {type: Delete}
        condition: {withState: ARCHIVED, daysSinceNoncurrentTime: 90}

• action.type is Delete, SetStorageClass (needs action.storageClass) or AbortIncompleteMultipartUpload.
• condition takes age, matchesPrefixes, matchesSuffixes, matchesStorageClasses, withState (LIVE | ARCHIVED | ANY), numNewerVersions and daysSinceNoncurrentTime; set at least one.
• With Autoclass enabled, SetStorageClass rules are rejected (Cloud Storage manages the classes).

Test

uv sync --extra dev
uv run pytest

The guardrail suites (layout, import rules, contracts, models) and the resource-graph snapshots run on eai_core_infra.testing, which other eai-*-infra packages use too (pip install "eai-core-infra[testing]"). Describe the package with a GuardrailSpec and call one assert_* per suite. RECORD_ALLOWLISTS=1 rewrites the ratchet allowlists and RECORD_SNAPSHOTS=1 rewrites snapshots; review every added line.

Pre-commit

Hooks mirror CI lint and tests (ruff check, pytest):

uv tool install pre-commit   # once
pre-commit install
pre-commit run --all-files   # optional manual run

License

Apache-2.0