svc-infra 0.1.623__py3-none-any.whl → 0.1.625__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.

This version of svc-infra might be problematic. Click here for more details.

Files changed (7) hide show
  1. svc_infra/cli/cmds/help.py +4 -0
  2. svc_infra/docs/getting-started.md +63 -0
  3. svc_infra/mcp/svc_infra_mcp.py +48 -2
  4. {svc_infra-0.1.623.dist-info → svc_infra-0.1.625.dist-info}/METADATA +23 -14
  5. {svc_infra-0.1.623.dist-info → svc_infra-0.1.625.dist-info}/RECORD +7 -6
  6. {svc_infra-0.1.623.dist-info → svc_infra-0.1.625.dist-info}/WHEEL +0 -0
  7. {svc_infra-0.1.623.dist-info → svc_infra-0.1.625.dist-info}/entry_points.txt +0 -0
svc_infra/cli/cmds/help.py CHANGED
@@ -21,4 +21,8 @@ How to run (pick what fits your workflow):
21
21
  Notes:
22
22
  * Make sure you’re in the right virtual environment (or use `pipx`).
23
23
  * You can point `--project-root` at your Alembic root; if omitted we auto-detect.
24
+
25
+ Learn more:
26
+ * For full integration guides and all topics, run: `svc-infra docs list`
27
+ * To explore docs commands, run: `svc-infra docs --help`
24
28
  """
svc_infra/docs/getting-started.md ADDED
@@ -0,0 +1,63 @@
1
+ # svc-infra
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
4
+ [![Docs](https://img.shields.io/badge/docs-reference-blue)](.)
5
+
6
+ svc-infra packages the shared building blocks we use to ship production FastAPI services fast—HTTP APIs with secure auth, durable persistence, background execution, cache, observability, and webhook plumbing that all share the same batteries-included defaults.
7
+
8
+ ## Helper index
9
+
10
+ | Area | What it covers | Guide |
11
+ | --- | --- | --- |
12
+ | Getting Started | Overview and entry points | [This page](getting-started.md) |
13
+ | Environment | Feature switches and env vars | [Environment](environment.md) |
14
+ | API | FastAPI bootstrap, middleware, docs wiring | [API guide](api.md) |
15
+ | Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth](auth.md) |
16
+ | Security | Password policy, lockout, signed cookies, headers | [Security](security.md) |
17
+ | Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database](database.md) |
18
+ | Tenancy | Multi-tenant boundaries and helpers | [Tenancy](tenancy.md) |
19
+ | Idempotency | Idempotent endpoints and middleware | [Idempotency](idempotency.md) |
20
+ | Rate Limiting | Middleware, dependency limiter, headers | [Rate limiting](rate-limiting.md) |
21
+ | Cache | cashews decorators, namespace management, TTL helpers | [Cache](cache.md) |
22
+ | Jobs | JobQueue, scheduler, CLI worker | [Jobs](jobs.md) |
23
+ | Observability | Prometheus, Grafana, OpenTelemetry | [Observability](observability.md) |
24
+ | Ops | Probes, breakers, SLOs & dashboards | [Ops](ops.md) |
25
+ | Webhooks | Subscription store, signing, retry worker | [Webhooks](webhooks.md) |
26
+ | CLI | Command groups for sql/mongo/obs/docs/dx/sdk/jobs | [CLI](cli.md) |
27
+ | Docs & SDKs | Publishing docs, generating SDKs | [Docs & SDKs](docs-and-sdks.md) |
28
+ | Acceptance | Acceptance harness and flows | [Acceptance](acceptance.md), [Matrix](acceptance-matrix.md) |
29
+ | Contributing | Dev setup and quality gates | [Contributing](contributing.md) |
30
+ | Repo Review | Checklist for releasing/PRs | [Repo review](repo-review.md) |
31
+ | Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](data-lifecycle.md) |
32
+
33
+ ## Minimal FastAPI bootstrap
34
+
35
+ ```python
36
+ from fastapi import Depends
37
+ from svc_infra.api.fastapi.ease import easy_service_app
38
+ from svc_infra.api.fastapi.db.sql.add import add_sql_db
39
+ from svc_infra.cache import init_cache
40
+ from svc_infra.jobs.easy import easy_jobs
41
+ from svc_infra.webhooks.fastapi import require_signature
42
+
43
+ app = easy_service_app(name="Billing", release="1.2.3")
44
+ add_sql_db(app) # reads SQL_URL / DB_* envs
45
+ init_cache() # honors CACHE_PREFIX / CACHE_VERSION
46
+ queue, scheduler = easy_jobs() # switches via JOBS_DRIVER / REDIS_URL
47
+
48
+ @app.post("/webhooks/billing")
49
+ async def handle_webhook(payload = Depends(require_signature(lambda: ["current", "next"]))):
50
+ queue.enqueue("process-billing-webhook", payload)
51
+ return {"status": "queued"}
52
+ ```
53
+
54
+ ## Environment switches
55
+
56
+ - **API** – toggle logging/observability and docs exposure with `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and `CORS_ALLOW_ORIGINS`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
57
+ - **Auth** – configure JWT secrets, SMTP, cookies, and policy using the `AUTH_…` settings family (e.g., `AUTH_JWT__SECRET`, `AUTH_SMTP_HOST`, `AUTH_SESSION_COOKIE_SECURE`). 【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
58
+ - **Database** – set connection URLs or components via `SQL_URL`/`SQL_URL_FILE`, `DB_DIALECT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, plus Mongo knobs like `MONGO_URL`, `MONGO_DB`, and `MONGO_URL_FILE`. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L55-L114】【F:src/svc_infra/db/sql/utils.py†L85-L206】【F:src/svc_infra/db/nosql/mongo/settings.py†L9-L13】【F:src/svc_infra/db/nosql/utils.py†L56-L113】
59
+ - **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:src/svc_infra/docs/jobs.md†L11-L48】
60
+ - **Cache** – namespace keys and lifetimes through `CACHE_PREFIX`, `CACHE_VERSION`, and TTL overrides `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG`. 【F:src/svc_infra/cache/README.md†L20-L173】【F:src/svc_infra/cache/ttl.py†L26-L55】
61
+ - **Observability** – turn metrics on/off or adjust scrape paths with `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and Prometheus/Grafana flags like `SVC_INFRA_DISABLE_PROMETHEUS`, `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
62
+ - **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:src/svc_infra/docs/webhooks.md†L32-L53】
63
+ - **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:src/svc_infra/docs/security.md†L24-L70】
svc_infra/mcp/svc_infra_mcp.py CHANGED
@@ -2,10 +2,11 @@ from __future__ import annotations
2
2
 
3
3
  from enum import Enum
4
4
 
5
- from ai_infra.llm.tools.custom.cli import cli_cmd_help, cli_subcmd_help
5
+ from ai_infra.llm.tools.custom.cli import cli_cmd_help, cli_subcmd_help, run_cli
6
+ from ai_infra.mcp.server.tools import mcp_from_functions
7
+
6
8
  from svc_infra.app.env import prepare_env
7
9
  from svc_infra.cli.foundation.runner import run_from_root
8
- from ai_infra.mcp.server.tools import mcp_from_functions
9
10
 
10
11
  CLI_PROG = "svc-infra"
11
12
 
@@ -19,6 +20,25 @@ async def svc_infra_cmd_help() -> dict:
19
20
  return await cli_cmd_help(CLI_PROG)
20
21
 
21
22
 
23
+ async def svc_infra_docs_list() -> dict:
24
+ """Run `svc-infra docs list` and return its output.
25
+
26
+ Uses run_cli with the project root as cwd; falls back to run_from_root if needed.
27
+ """
28
+ root = prepare_env()
29
+ try:
30
+ text = await run_cli(CLI_PROG, ["docs", "list"], cwd=str(root))
31
+ except TypeError:
32
+ # Fallback for older run_cli signatures
33
+ text = await run_from_root(root, CLI_PROG, ["docs", "list"])
34
+ return {
35
+ "ok": True,
36
+ "action": "docs_list",
37
+ "project_root": str(root),
38
+ "output": text,
39
+ }
40
+
41
+
22
42
  class Subcommand(str, Enum):
23
43
  # SQL group commands
24
44
  sql_init = "sql init"
@@ -34,6 +54,7 @@ class Subcommand(str, Enum):
34
54
  sql_scaffold_models = "sql scaffold-models"
35
55
  sql_scaffold_schemas = "sql scaffold-schemas"
36
56
  sql_export_tenant = "sql export-tenant"
57
+ sql_seed = "sql seed"
37
58
 
38
59
  # Mongo group commands
39
60
  mongo_prepare = "mongo prepare"
@@ -49,6 +70,24 @@ class Subcommand(str, Enum):
49
70
  obs_down = "obs down"
50
71
  obs_scaffold = "obs scaffold"
51
72
 
73
+ # Docs group
74
+ docs_list = "docs list"
75
+ docs_show = "docs show"
76
+
77
+ # DX group
78
+ dx_openapi = "dx openapi"
79
+ dx_migrations = "dx migrations"
80
+ dx_changelog = "dx changelog"
81
+ dx_ci = "dx ci"
82
+
83
+ # Jobs group
84
+ jobs_run = "jobs run"
85
+
86
+ # SDK group
87
+ sdk_ts = "sdk ts"
88
+ sdk_py = "sdk py"
89
+ sdk_postman = "sdk postman"
90
+
52
91
 
53
92
  async def svc_infra_subcmd_help(subcommand: Subcommand) -> dict:
54
93
  """
@@ -75,8 +114,15 @@ mcp = mcp_from_functions(
75
114
  functions=[
76
115
  svc_infra_cmd_help,
77
116
  svc_infra_subcmd_help,
117
+ svc_infra_docs_list,
118
+ # Utility: list docs topics via `svc-infra docs list`
119
+ # Exposed as a dedicated MCP function for quick discovery in clients.
120
+ # See: svc_infra.cli.cmds.docs.docs_cmds
121
+ # NOTE: Prefer run_cli with cwd=project root; fallback to run_from_root if signature differs.
122
+ # Implemented as an inline wrapper to keep the API surface minimal.
78
123
  ],
79
124
  )
80
125
 
126
+
81
127
  if __name__ == "__main__":
82
128
  mcp.run(transport="stdio")
{svc_infra-0.1.623.dist-info → svc_infra-0.1.625.dist-info}/METADATA RENAMED
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: svc-infra
3
- Version: 0.1.623
3
+ Version: 0.1.625
4
4
  Summary: Infrastructure for building and deploying prod-ready services
5
5
  License: MIT
6
6
  Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
@@ -77,25 +77,34 @@ Description-Content-Type: text/markdown
77
77
  # svc-infra
78
78
 
79
79
  [![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
80
- [![Docs](https://img.shields.io/badge/docs-reference-blue)](src/svc_infra/docs/)
80
+ [![Docs](https://img.shields.io/badge/docs-reference-blue)](.)
81
81
 
82
82
  svc-infra packages the shared building blocks we use to ship production FastAPI services fast—HTTP APIs with secure auth, durable persistence, background execution, cache, observability, and webhook plumbing that all share the same batteries-included defaults.
83
83
 
84
84
  ## Helper index
85
85
 
86
- | Helper | What it covers | Guide |
86
+ | Area | What it covers | Guide |
87
87
  | --- | --- | --- |
88
- | API | FastAPI bootstrap, envelopes, middleware, docs wiring | [FastAPI guide](src/svc_infra/docs/api.md) |
89
- | Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth settings](src/svc_infra/docs/auth.md) |
90
- | Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database guide](src/svc_infra/docs/database.md) |
91
- | Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](src/svc_infra/docs/jobs.md) |
92
- | Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](src/svc_infra/docs/cache.md) |
93
- | Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](src/svc_infra/docs/observability.md) |
94
- | Ops | Probes, breaker, SLOs & dashboards | [SLOs & Ops](src/svc_infra/docs/ops.md) |
95
- | Webhooks | Subscription store, signing, retry worker | [Webhooks framework](src/svc_infra/docs/webhooks.md) |
96
- | Security | Password policy, lockout, signed cookies, headers | [Security hardening](src/svc_infra/docs/security.md) |
97
- | Contributing | Dev setup and quality gates | [Contributing guide](src/svc_infra/docs/contributing.md) |
98
- | Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](src/svc_infra/docs/data-lifecycle.md) |
88
+ | Getting Started | Overview and entry points | [This page](getting-started.md) |
89
+ | Environment | Feature switches and env vars | [Environment](environment.md) |
90
+ | API | FastAPI bootstrap, middleware, docs wiring | [API guide](api.md) |
91
+ | Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth](auth.md) |
92
+ | Security | Password policy, lockout, signed cookies, headers | [Security](security.md) |
93
+ | Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database](database.md) |
94
+ | Tenancy | Multi-tenant boundaries and helpers | [Tenancy](tenancy.md) |
95
+ | Idempotency | Idempotent endpoints and middleware | [Idempotency](idempotency.md) |
96
+ | Rate Limiting | Middleware, dependency limiter, headers | [Rate limiting](rate-limiting.md) |
97
+ | Cache | cashews decorators, namespace management, TTL helpers | [Cache](cache.md) |
98
+ | Jobs | JobQueue, scheduler, CLI worker | [Jobs](jobs.md) |
99
+ | Observability | Prometheus, Grafana, OpenTelemetry | [Observability](observability.md) |
100
+ | Ops | Probes, breakers, SLOs & dashboards | [Ops](ops.md) |
101
+ | Webhooks | Subscription store, signing, retry worker | [Webhooks](webhooks.md) |
102
+ | CLI | Command groups for sql/mongo/obs/docs/dx/sdk/jobs | [CLI](cli.md) |
103
+ | Docs & SDKs | Publishing docs, generating SDKs | [Docs & SDKs](docs-and-sdks.md) |
104
+ | Acceptance | Acceptance harness and flows | [Acceptance](acceptance.md), [Matrix](acceptance-matrix.md) |
105
+ | Contributing | Dev setup and quality gates | [Contributing](contributing.md) |
106
+ | Repo Review | Checklist for releasing/PRs | [Repo review](repo-review.md) |
107
+ | Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](data-lifecycle.md) |
99
108
 
100
109
  ## Minimal FastAPI bootstrap
101
110
 
{svc_infra-0.1.623.dist-info → svc_infra-0.1.625.dist-info}/RECORD RENAMED
@@ -145,7 +145,7 @@ svc_infra/cli/cmds/db/sql/sql_scaffold_cmds.py,sha256=MKc_T_tY1Y_wQl7XTlq8GhYWMM
145
145
  svc_infra/cli/cmds/docs/docs_cmds.py,sha256=Gyi0cr22-SY8kThAutRSzW9LmZ1ek9LTpwFpvlclKWM,6407
146
146
  svc_infra/cli/cmds/dx/__init__.py,sha256=wQtl3-kOgoESlpVkjl3YFtqkOnQSIvVsOdutiaZFejM,197
147
147
  svc_infra/cli/cmds/dx/dx_cmds.py,sha256=XTKUJzS3UIYn6h3CHzDEWKYJaWn0TzGiUCq3OeW27E0,3326
148
- svc_infra/cli/cmds/help.py,sha256=wGfZFMYaR2ZPwW2JwKDU7M3m4AtdCd8GRQ412AmEBUM,758
148
+ svc_infra/cli/cmds/help.py,sha256=kNbaWkppGfEiWUhOwekAMDr3DEkOUzXGyrNLSR3T5qI,901
149
149
  svc_infra/cli/cmds/jobs/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
150
150
  svc_infra/cli/cmds/jobs/jobs_cmds.py,sha256=l-w5GuR82GWR_F1CA7WPYAM895XBD8TQj_hZ6retBv0,1252
151
151
  svc_infra/cli/cmds/obs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -235,6 +235,7 @@ svc_infra/docs/data-lifecycle.md,sha256=_XFZCj9qiYgEiN9jO_lq7RcpVIeLVN7REaFziiNC
235
235
  svc_infra/docs/database.md,sha256=p_t-4ApQqa7ImhiV6wv0oklDTEZPn-snO1K1FoNtZpI,1129
236
236
  svc_infra/docs/docs-and-sdks.md,sha256=v5Uz-CVNswiZ-ITiqo6tiOX5xGJSnftfbA7b3hrqHqI,2330
237
237
  svc_infra/docs/environment.md,sha256=w84-1hL3zog6fYYgDLiQRQiAlS2CadjmZmu87Frzxy8,9700
238
+ svc_infra/docs/getting-started.md,sha256=B1ns6Zm_LOGtncuBafxVb2yGHSqRkUsncytJw6RxSbU,5262
238
239
  svc_infra/docs/idempotency.md,sha256=jvemdVY4g6xoHW38OAZIS5JxA3SdK8a0iAayx18kIbk,3890
239
240
  svc_infra/docs/jobs.md,sha256=iyDPo6oo7fJdBZ9e6Qt9x_kX4sX7_TUUdY89CFiZ61I,1586
240
241
  svc_infra/docs/observability.md,sha256=qzu44CSmGwjdLkBj0TQ1LBMmXd7BO2hmJSdByZlBXck,1021
@@ -256,7 +257,7 @@ svc_infra/jobs/redis_queue.py,sha256=wgmWKslF1dkYscJe49UgUX7gwEuGyOUWEb0-pn82I3g
256
257
  svc_infra/jobs/scheduler.py,sha256=dTUEEyEuTVHNmJT8wPdMu4YjnTN7R_YW67gtCKpqC7M,1180
257
258
  svc_infra/jobs/worker.py,sha256=T2A575_mnieJHPOYU_FseubLA_HQf9pB4CkRgzRJBHU,694
258
259
  svc_infra/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
259
- svc_infra/mcp/svc_infra_mcp.py,sha256=x8wEB1YhnM2X3_3AUmKl6qKmQcL63dGbJ71WlzigHs8,2423
260
+ svc_infra/mcp/svc_infra_mcp.py,sha256=xz67oXIoEOZaFbyRn3_uda-SXmruOXtyF0OZuLX_LnA,3771
260
261
  svc_infra/obs/README.md,sha256=pmd6AyFZW3GCCi0sr3uTHrPj5KgAI8rrXw8QPkrf1R8,8021
261
262
  svc_infra/obs/__init__.py,sha256=t5DgkiuuhHnfAHChzYqCI1-Fpr68iQ0A1nHOLFIlAuM,75
262
263
  svc_infra/obs/add.py,sha256=Qa8pswZDxspIn3oniqe8NYeHmVhFwiYOYxF9xNAyCOs,4016
@@ -324,7 +325,7 @@ svc_infra/webhooks/fastapi.py,sha256=BCNvGNxukf6dC2a4i-6en-PrjBGV19YvCWOot5lXWsA
324
325
  svc_infra/webhooks/router.py,sha256=6JvAVPMEth_xxHX-IsIOcyMgHX7g1H0OVxVXKLuMp9w,1596
325
326
  svc_infra/webhooks/service.py,sha256=hWgiJRXKBwKunJOx91C7EcLUkotDtD3Xp0RT6vj2IC0,1797
326
327
  svc_infra/webhooks/signing.py,sha256=NCwdZzmravUe7HVIK_uXK0qqf12FG-_MVsgPvOw6lsM,784
327
- svc_infra-0.1.623.dist-info/METADATA,sha256=b0847FKVzDHLtuU1uxB7G6qubJkOqpztMsuZmEhK43I,8316
328
- svc_infra-0.1.623.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
329
- svc_infra-0.1.623.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
330
- svc_infra-0.1.623.dist-info/RECORD,,
328
+ svc_infra-0.1.625.dist-info/METADATA,sha256=gSopiurNf48SuyU4cG8H92kkgvZuB0XL51RKDZiohy4,8748
329
+ svc_infra-0.1.625.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
330
+ svc_infra-0.1.625.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
331
+ svc_infra-0.1.625.dist-info/RECORD,,