sandloom 0.7.0a1__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.
- sandloom/__init__.py +349 -0
- sandloom/core/AGENTS.md +120 -0
- sandloom/core/CLAUDE.md +1 -0
- sandloom/core/__init__.py +10 -0
- sandloom/core/_internal/__init__.py +6 -0
- sandloom/core/_internal/db_provider.py +53 -0
- sandloom/core/admin/__init__.py +5 -0
- sandloom/core/admin/api/__init__.py +1 -0
- sandloom/core/admin/api/platform.py +754 -0
- sandloom/core/admin/compiler.py +529 -0
- sandloom/core/admin/models.py +106 -0
- sandloom/core/app_factory.py +1135 -0
- sandloom/core/archcheck/__init__.py +22 -0
- sandloom/core/archcheck/analyzers.py +1830 -0
- sandloom/core/archcheck/api10_rules.py +952 -0
- sandloom/core/archcheck/manifest.py +286 -0
- sandloom/core/archcheck/module_rules.py +546 -0
- sandloom/core/archcheck/runner.py +685 -0
- sandloom/core/async_runner.py +195 -0
- sandloom/core/auth/__init__.py +7 -0
- sandloom/core/auth/bearer.py +118 -0
- sandloom/core/auth/blocks.py +277 -0
- sandloom/core/auth/hashing.py +232 -0
- sandloom/core/auth/marks.py +307 -0
- sandloom/core/auth/recovery.py +384 -0
- sandloom/core/auth/revocation.py +393 -0
- sandloom/core/auth/tokens.py +361 -0
- sandloom/core/auth/verification.py +238 -0
- sandloom/core/beat_lease.py +387 -0
- sandloom/core/claims.py +29 -0
- sandloom/core/cli/__init__.py +0 -0
- sandloom/core/cli/_operator.py +71 -0
- sandloom/core/cli/add.py +1467 -0
- sandloom/core/cli/admin.py +41 -0
- sandloom/core/cli/backup.py +265 -0
- sandloom/core/cli/check.py +242 -0
- sandloom/core/cli/config.py +283 -0
- sandloom/core/cli/contracts.py +231 -0
- sandloom/core/cli/doctor.py +627 -0
- sandloom/core/cli/dto_copies.py +695 -0
- sandloom/core/cli/events.py +320 -0
- sandloom/core/cli/explain.py +61 -0
- sandloom/core/cli/extract.py +1311 -0
- sandloom/core/cli/generated.py +1354 -0
- sandloom/core/cli/gunicorn_conf.py +319 -0
- sandloom/core/cli/image_secrets.py +161 -0
- sandloom/core/cli/keys.py +344 -0
- sandloom/core/cli/migrate.py +679 -0
- sandloom/core/cli/migrate_drift.py +156 -0
- sandloom/core/cli/migrate_rls.py +102 -0
- sandloom/core/cli/project.py +1164 -0
- sandloom/core/cli/projections.py +144 -0
- sandloom/core/cli/route_weakening.py +212 -0
- sandloom/core/cli/routes.py +120 -0
- sandloom/core/cli/run_tests.py +521 -0
- sandloom/core/cli/sagas.py +306 -0
- sandloom/core/cli/scaffold_deploy.py +969 -0
- sandloom/core/cli/scaffold_wiring.py +183 -0
- sandloom/core/cli/security.py +408 -0
- sandloom/core/cli/skills.py +62 -0
- sandloom/core/cli/templates/api-cheatsheet.md +54 -0
- sandloom/core/cli/templates/deploy/compose/microservices.yml.tmpl +311 -0
- sandloom/core/cli/templates/deploy/gateway/nginx.conf +71 -0
- sandloom/core/cli/templates/deploy/postgres/init-databases.sh +26 -0
- sandloom/core/cli/templates/module-AGENTS.md +120 -0
- sandloom/core/cli/templates/skills/sandloom-event-version-roll/SKILL.md +55 -0
- sandloom/core/cli/templates/skills/sandloom-new-module/SKILL.md +57 -0
- sandloom/core/cli/templates/skills/sandloom-quality-gates/SKILL.md +52 -0
- sandloom/core/cli/templates/skills/sandloom-split-deploy/SKILL.md +50 -0
- sandloom/core/cli/tool_process.py +36 -0
- sandloom/core/composition.py +95 -0
- sandloom/core/config/__init__.py +7 -0
- sandloom/core/config/accepted_risks.py +189 -0
- sandloom/core/config/auth.py +141 -0
- sandloom/core/config/cache.py +40 -0
- sandloom/core/config/common.py +118 -0
- sandloom/core/config/contracts.py +147 -0
- sandloom/core/config/database.py +123 -0
- sandloom/core/config/eventing.py +172 -0
- sandloom/core/config/http.py +73 -0
- sandloom/core/config/infra.py +20 -0
- sandloom/core/config/modules.py +81 -0
- sandloom/core/config/observability.py +30 -0
- sandloom/core/config/password_params.py +120 -0
- sandloom/core/config/replay_limits.py +28 -0
- sandloom/core/config/rpc.py +94 -0
- sandloom/core/config/runtime.py +136 -0
- sandloom/core/config/sagas.py +40 -0
- sandloom/core/config/services.py +50 -0
- sandloom/core/config/settings.py +775 -0
- sandloom/core/config/tiers.py +982 -0
- sandloom/core/config/trust.py +76 -0
- sandloom/core/consumers/__init__.py +7 -0
- sandloom/core/consumers/callbacks.py +424 -0
- sandloom/core/consumers/runtime.py +636 -0
- sandloom/core/contract_cache_shadow.py +953 -0
- sandloom/core/contract_compat.py +684 -0
- sandloom/core/contract_context.py +71 -0
- sandloom/core/contract_testing.py +488 -0
- sandloom/core/contract_wire.py +847 -0
- sandloom/core/contracts/__init__.py +43 -0
- sandloom/core/contracts/payload_validation.py +168 -0
- sandloom/core/contracts/schema_registry.py +114 -0
- sandloom/core/contracts/uow.py +56 -0
- sandloom/core/contracts/validators.py +255 -0
- sandloom/core/cpu_quota.py +66 -0
- sandloom/core/descriptors/__init__.py +318 -0
- sandloom/core/descriptors/contract_refs.py +80 -0
- sandloom/core/descriptors/module_names.py +164 -0
- sandloom/core/descriptors/sagas.py +695 -0
- sandloom/core/di.py +994 -0
- sandloom/core/drivers/__init__.py +0 -0
- sandloom/core/drivers/bootstrap.py +221 -0
- sandloom/core/drivers/celery_taskqueue.py +242 -0
- sandloom/core/drivers/event_bus_driver.py +241 -0
- sandloom/core/drivers/filesystem_storage.py +155 -0
- sandloom/core/drivers/linger_pool.py +358 -0
- sandloom/core/drivers/local_objectstore.py +221 -0
- sandloom/core/drivers/log_notifier.py +107 -0
- sandloom/core/drivers/memory_document_store.py +123 -0
- sandloom/core/drivers/redis_cache.py +836 -0
- sandloom/core/drivers/smtp_notifier.py +128 -0
- sandloom/core/drivers/sqlalchemy_database.py +913 -0
- sandloom/core/drivers/system_db.py +160 -0
- sandloom/core/effects.py +286 -0
- sandloom/core/error_codes.py +1350 -0
- sandloom/core/eventing/__init__.py +0 -0
- sandloom/core/eventing/bus_base.py +346 -0
- sandloom/core/eventing/bus_metrics.py +49 -0
- sandloom/core/eventing/consumer_inbox.py +107 -0
- sandloom/core/eventing/core_events.py +116 -0
- sandloom/core/eventing/delivery.py +79 -0
- sandloom/core/eventing/envelope.py +132 -0
- sandloom/core/eventing/event_bus.py +63 -0
- sandloom/core/eventing/memory_bus.py +250 -0
- sandloom/core/eventing/memory_transport.py +355 -0
- sandloom/core/eventing/origin.py +41 -0
- sandloom/core/eventing/pubsub_bus.py +429 -0
- sandloom/core/eventing/streams_bus.py +477 -0
- sandloom/core/eventing/streams_consume.py +628 -0
- sandloom/core/eventing/streams_dispatch.py +325 -0
- sandloom/core/eventing/streams_groups.py +398 -0
- sandloom/core/eventing/streams_inventory.py +207 -0
- sandloom/core/eventing/streams_lease.py +100 -0
- sandloom/core/eventing/streams_transport.py +264 -0
- sandloom/core/eventing/streams_transport_base.py +185 -0
- sandloom/core/eventing/subscriptions.py +142 -0
- sandloom/core/eventing/transport_base.py +355 -0
- sandloom/core/eventing/transport_capabilities.py +122 -0
- sandloom/core/exceptions.py +57 -0
- sandloom/core/facade/__init__.py +313 -0
- sandloom/core/facade/_claims.py +476 -0
- sandloom/core/facade/_registries.py +365 -0
- sandloom/core/facade/_runtime.py +118 -0
- sandloom/core/facade/_services.py +294 -0
- sandloom/core/facade/_state.py +173 -0
- sandloom/core/gc_tuning.py +279 -0
- sandloom/core/guarantee_lattice.py +218 -0
- sandloom/core/guarantee_windows.py +256 -0
- sandloom/core/guard_order.py +293 -0
- sandloom/core/http/__init__.py +0 -0
- sandloom/core/http/error_handlers.py +302 -0
- sandloom/core/http/middlewares.py +597 -0
- sandloom/core/http/request_authority.py +93 -0
- sandloom/core/http/route_index.py +252 -0
- sandloom/core/http/route_runtime.py +592 -0
- sandloom/core/http/tenant_scope.py +186 -0
- sandloom/core/idempotency/__init__.py +72 -0
- sandloom/core/idempotency/automatic.py +166 -0
- sandloom/core/idempotency/cache_store.py +118 -0
- sandloom/core/idempotency/capture.py +251 -0
- sandloom/core/idempotency/durable.py +350 -0
- sandloom/core/idempotency/fingerprint.py +209 -0
- sandloom/core/idempotency/guard.py +207 -0
- sandloom/core/idempotency/replay.py +159 -0
- sandloom/core/idempotency/reservation.py +277 -0
- sandloom/core/infra/__init__.py +119 -0
- sandloom/core/infra/access.py +135 -0
- sandloom/core/infra/active.py +42 -0
- sandloom/core/infra/capabilities.py +207 -0
- sandloom/core/infra/config.py +218 -0
- sandloom/core/infra/contracts.py +1170 -0
- sandloom/core/infra/extra_capabilities.py +266 -0
- sandloom/core/infra/registry.py +831 -0
- sandloom/core/ingress/__init__.py +6 -0
- sandloom/core/ingress/client_ip.py +161 -0
- sandloom/core/ingress/rate_limit.py +213 -0
- sandloom/core/internal_auth.py +92 -0
- sandloom/core/lifecycle.py +210 -0
- sandloom/core/loader/__init__.py +0 -0
- sandloom/core/loader/manifest.py +445 -0
- sandloom/core/loader/plugin_loader.py +664 -0
- sandloom/core/migrations/__init__.py +45 -0
- sandloom/core/migrations/alembic_support.py +236 -0
- sandloom/core/migrations/backup.py +592 -0
- sandloom/core/migrations/core_chain/README +1 -0
- sandloom/core/migrations/core_chain/env.py +27 -0
- sandloom/core/migrations/core_chain/script.py.mako +28 -0
- sandloom/core/migrations/core_chain/versions/0001_core_infra_core_infrastructure_tables.py +110 -0
- sandloom/core/migrations/core_chain/versions/0002_outbox_lease.py +37 -0
- sandloom/core/migrations/core_chain/versions/0003_outbox_claim_token.py +37 -0
- sandloom/core/migrations/core_chain/versions/0004_outbox_backoff.py +37 -0
- sandloom/core/migrations/core_chain/versions/0005_outbox_partial_indexes.py +74 -0
- sandloom/core/migrations/core_chain/versions/0006_contract_command_log.py +55 -0
- sandloom/core/migrations/core_chain/versions/0007_consumer_inbox_processed_at.py +41 -0
- sandloom/core/migrations/core_chain/versions/0008_outbox_trace_id.py +23 -0
- sandloom/core/migrations/core_chain/versions/0009_http_idempotency_log.py +56 -0
- sandloom/core/migrations/core_chain/versions/0010_saga_state.py +133 -0
- sandloom/core/migrations/core_chain/versions/0011_projection_watermarks.py +41 -0
- sandloom/core/migrations/core_chain/versions/0012_projection_rebuilds_active.py +47 -0
- sandloom/core/migrations/core_chain/versions/0013_contract_command_effects.py +38 -0
- sandloom/core/migrations/migrations.py +930 -0
- sandloom/core/migrations/urls.py +61 -0
- sandloom/core/module_api/__init__.py +210 -0
- sandloom/core/module_api/_bootstrap.py +52 -0
- sandloom/core/module_api/_call.py +460 -0
- sandloom/core/module_api/_context.py +125 -0
- sandloom/core/module_api/_dedupe.py +393 -0
- sandloom/core/module_api/_define.py +186 -0
- sandloom/core/module_api/_errors.py +187 -0
- sandloom/core/module_api/_method.py +224 -0
- sandloom/core/module_api/_provider.py +396 -0
- sandloom/core/module_api/_read_guard.py +57 -0
- sandloom/core/module_api/_read_scope.py +492 -0
- sandloom/core/module_api/_registration.py +572 -0
- sandloom/core/module_api/_schema.py +280 -0
- sandloom/core/module_api/_service_registry.py +134 -0
- sandloom/core/module_api/_spec.py +97 -0
- sandloom/core/observability/__init__.py +0 -0
- sandloom/core/observability/guardrails.py +221 -0
- sandloom/core/observability/logging.py +192 -0
- sandloom/core/observability/metrics.py +763 -0
- sandloom/core/observability/metrics_utils.py +27 -0
- sandloom/core/observability/observability.py +131 -0
- sandloom/core/observability/request_context.py +16 -0
- sandloom/core/observability/tracing.py +137 -0
- sandloom/core/orm.py +69 -0
- sandloom/core/planner.py +979 -0
- sandloom/core/production_profile.py +310 -0
- sandloom/core/projections/__init__.py +54 -0
- sandloom/core/projections/consumer.py +61 -0
- sandloom/core/projections/descriptors.py +162 -0
- sandloom/core/projections/operations.py +232 -0
- sandloom/core/projections/purge.py +268 -0
- sandloom/core/projections/rebuild.py +131 -0
- sandloom/core/projections/registry.py +129 -0
- sandloom/core/projections/stores.py +262 -0
- sandloom/core/projections/tokens.py +304 -0
- sandloom/core/projections/upsert.py +230 -0
- sandloom/core/route_markers.py +256 -0
- sandloom/core/route_policy.py +532 -0
- sandloom/core/route_snapshots.py +426 -0
- sandloom/core/rpc/__init__.py +217 -0
- sandloom/core/rpc/binding.py +237 -0
- sandloom/core/rpc/client.py +154 -0
- sandloom/core/rpc/context.py +210 -0
- sandloom/core/rpc/dispatch.py +246 -0
- sandloom/core/rpc/envelope.py +208 -0
- sandloom/core/rpc/errors.py +67 -0
- sandloom/core/rpc/inbound_auth.py +358 -0
- sandloom/core/rpc/outbound.py +120 -0
- sandloom/core/rpc/proxy.py +757 -0
- sandloom/core/rpc/readiness.py +345 -0
- sandloom/core/rpc/server.py +393 -0
- sandloom/core/rpc/wire.py +88 -0
- sandloom/core/rpc_binding.py +465 -0
- sandloom/core/rpc_identity.py +368 -0
- sandloom/core/rpc_pair_mac.py +831 -0
- sandloom/core/rpc_transport.py +687 -0
- sandloom/core/rpc_transport_compat.py +416 -0
- sandloom/core/runtime.py +98 -0
- sandloom/core/sagas/__init__.py +196 -0
- sandloom/core/sagas/channel.py +156 -0
- sandloom/core/sagas/ops.py +528 -0
- sandloom/core/sagas/outcomes.py +231 -0
- sandloom/core/sagas/registry.py +315 -0
- sandloom/core/sagas/runtime.py +992 -0
- sandloom/core/sagas/sweep.py +233 -0
- sandloom/core/schema/__init__.py +0 -0
- sandloom/core/schema/registry.py +220 -0
- sandloom/core/signing_keys.py +248 -0
- sandloom/core/sql_alchemy/__init__.py +1 -0
- sandloom/core/sql_alchemy/base.py +17 -0
- sandloom/core/sql_alchemy/columns.py +134 -0
- sandloom/core/sql_alchemy/command_log.py +193 -0
- sandloom/core/sql_alchemy/dead_connection.py +343 -0
- sandloom/core/sql_alchemy/dedupe_log.py +380 -0
- sandloom/core/sql_alchemy/driver_compat.py +470 -0
- sandloom/core/sql_alchemy/durable_inbox.py +131 -0
- sandloom/core/sql_alchemy/effect_rows.py +448 -0
- sandloom/core/sql_alchemy/models/__init__.py +37 -0
- sandloom/core/sql_alchemy/models/audit.py +50 -0
- sandloom/core/sql_alchemy/models/consumer_inbox.py +59 -0
- sandloom/core/sql_alchemy/models/contract_command.py +53 -0
- sandloom/core/sql_alchemy/models/http_idempotency.py +56 -0
- sandloom/core/sql_alchemy/models/outbox.py +130 -0
- sandloom/core/sql_alchemy/models/projection_watermark.py +31 -0
- sandloom/core/sql_alchemy/models/saga.py +136 -0
- sandloom/core/sql_alchemy/money_ledger.py +94 -0
- sandloom/core/sql_alchemy/outbox_store/__init__.py +509 -0
- sandloom/core/sql_alchemy/outbox_store/audit.py +144 -0
- sandloom/core/sql_alchemy/outbox_store/relay.py +549 -0
- sandloom/core/sql_alchemy/outbox_store/statements.py +125 -0
- sandloom/core/sql_alchemy/planner_adapter/__init__.py +362 -0
- sandloom/core/sql_alchemy/planner_adapter/compiler.py +673 -0
- sandloom/core/sql_alchemy/planner_adapter/forms.py +529 -0
- sandloom/core/sql_alchemy/planner_adapter/units.py +460 -0
- sandloom/core/sql_alchemy/planner_safety.py +213 -0
- sandloom/core/sql_alchemy/projection_watermarks.py +207 -0
- sandloom/core/sql_alchemy/read_guard.py +116 -0
- sandloom/core/sql_alchemy/read_only_policy.py +88 -0
- sandloom/core/sql_alchemy/reconnect.py +97 -0
- sandloom/core/sql_alchemy/repositories/__init__.py +1 -0
- sandloom/core/sql_alchemy/repositories/outbox.py +28 -0
- sandloom/core/sql_alchemy/request_log.py +184 -0
- sandloom/core/sql_alchemy/rls.py +210 -0
- sandloom/core/sql_alchemy/saga_store.py +434 -0
- sandloom/core/sql_alchemy/tenant_rls.py +696 -0
- sandloom/core/sql_alchemy/uow.py +93 -0
- sandloom/core/sql_alchemy/write_admission.py +462 -0
- sandloom/core/tasks/__init__.py +1 -0
- sandloom/core/tasks/enqueue.py +127 -0
- sandloom/core/tasks/event_ops.py +155 -0
- sandloom/core/tasks/periodic.py +39 -0
- sandloom/core/tasks/pool_metrics.py +87 -0
- sandloom/core/tasks/relay.py +826 -0
- sandloom/core/tenant.py +643 -0
- sandloom/core/tenant_context.py +100 -0
- sandloom/core/testing/__init__.py +236 -0
- sandloom/core/testing/_uow.py +450 -0
- sandloom/core/testing/auth.py +87 -0
- sandloom/core/testing/authz.py +183 -0
- sandloom/core/testing/boot.py +209 -0
- sandloom/core/testing/connections.py +195 -0
- sandloom/core/testing/database.py +367 -0
- sandloom/core/testing/deploy_profile.py +1088 -0
- sandloom/core/testing/env.py +83 -0
- sandloom/core/testing/events.py +143 -0
- sandloom/core/testing/fixtures.py +558 -0
- sandloom/core/testing/infra.py +52 -0
- sandloom/core/testing/isolation.py +236 -0
- sandloom/core/testing/migrations.py +312 -0
- sandloom/core/testing/observed.py +91 -0
- sandloom/core/testing/ownership.py +314 -0
- sandloom/core/testing/plugin.py +104 -0
- sandloom/core/testing/registration.py +135 -0
- sandloom/core/testing/resources.py +535 -0
- sandloom/core/testing/routes.py +86 -0
- sandloom/core/testing/sagas.py +755 -0
- sandloom/core/testing/security.py +129 -0
- sandloom/core/testing/served.py +262 -0
- sandloom/core/testing/server_errors.py +77 -0
- sandloom/core/testing/services.py +57 -0
- sandloom/core/testing/session_checks.py +175 -0
- sandloom/core/testing/shuffle.py +112 -0
- sandloom/core/testing/static_checks.py +318 -0
- sandloom/core/testing/workers.py +364 -0
- sandloom/core/unit_of_work/__init__.py +488 -0
- sandloom/core/unit_of_work/dispatch.py +626 -0
- sandloom/core/unit_of_work/effects.py +266 -0
- sandloom/core/unit_of_work/hooks.py +314 -0
- sandloom/core/unit_of_work/intent.py +398 -0
- sandloom/core/unit_of_work/request.py +574 -0
- sandloom/core/unit_of_work/risk.py +838 -0
- sandloom/core/unit_of_work/savepoints.py +68 -0
- sandloom/core/unit_of_work/scope.py +325 -0
- sandloom/core/unit_of_work/versioning.py +82 -0
- sandloom/core/utils.py +11 -0
- sandloom/core/worker.py +420 -0
- sandloom/main.py +48 -0
- sandloom/py.typed +0 -0
- sandloom/sdk/__init__.py +74 -0
- sandloom/sdk/_decl/__init__.py +13 -0
- sandloom/sdk/_decl/_caller.py +152 -0
- sandloom/sdk/_decl/_event_wire.py +1065 -0
- sandloom/sdk/_decl/_owner.py +103 -0
- sandloom/sdk/_decl/_recording.py +36 -0
- sandloom/sdk/_decl/contracts.py +520 -0
- sandloom/sdk/_decl/errors.py +79 -0
- sandloom/sdk/_decl/events.py +594 -0
- sandloom/sdk/_decl/module.py +592 -0
- sandloom/sdk/_decl/projections.py +1051 -0
- sandloom/sdk/_decl/sagas.py +110 -0
- sandloom/sdk/_decl/testing.py +89 -0
- sandloom/sdk/_decl/web.py +276 -0
- sandloom/sdk/_prim/__init__.py +12 -0
- sandloom/sdk/_prim/app.py +59 -0
- sandloom/sdk/_prim/authz.py +12 -0
- sandloom/sdk/_prim/contracts.py +96 -0
- sandloom/sdk/_prim/data.py +47 -0
- sandloom/sdk/_prim/docs.py +253 -0
- sandloom/sdk/_prim/docs_wire.py +322 -0
- sandloom/sdk/_prim/effects.py +13 -0
- sandloom/sdk/_prim/events.py +24 -0
- sandloom/sdk/_prim/infra.py +13 -0
- sandloom/sdk/_prim/module.py +23 -0
- sandloom/sdk/_prim/projections.py +61 -0
- sandloom/sdk/_prim/recipes.py +987 -0
- sandloom/sdk/_prim/sagas.py +14 -0
- sandloom/sdk/_prim/tasks.py +111 -0
- sandloom/sdk/_prim/tenant.py +26 -0
- sandloom/sdk/_prim/testing.py +142 -0
- sandloom/sdk/_prim/web.py +113 -0
- sandloom/sdk/_stub.py +14 -0
- sandloom/sdk/app.py +26 -0
- sandloom/sdk/authz.py +151 -0
- sandloom/sdk/contracts.py +94 -0
- sandloom/sdk/data.py +88 -0
- sandloom/sdk/effects.py +41 -0
- sandloom/sdk/errors.py +93 -0
- sandloom/sdk/events.py +39 -0
- sandloom/sdk/infra.py +61 -0
- sandloom/sdk/migrations.py +24 -0
- sandloom/sdk/module.py +49 -0
- sandloom/sdk/projections.py +82 -0
- sandloom/sdk/sagas.py +54 -0
- sandloom/sdk/security.py +74 -0
- sandloom/sdk/tasks.py +24 -0
- sandloom/sdk/tenant.py +37 -0
- sandloom/sdk/testing/__init__.py +205 -0
- sandloom/sdk/testing/fixtures.py +114 -0
- sandloom/sdk/testing/plugin.py +99 -0
- sandloom/sdk/tooling.py +24 -0
- sandloom/sdk/web.py +96 -0
- sandloom/shared/README.md +58 -0
- sandloom/shared/__init__.py +0 -0
- sandloom/shared/authz/__init__.py +155 -0
- sandloom/shared/authz/_resolve.py +173 -0
- sandloom/shared/authz/account.py +263 -0
- sandloom/shared/authz/algebra.py +282 -0
- sandloom/shared/authz/atoms_claims.py +363 -0
- sandloom/shared/authz/atoms_fact.py +125 -0
- sandloom/shared/authz/atoms_live.py +231 -0
- sandloom/shared/authz/atoms_resource.py +43 -0
- sandloom/shared/authz/constants.py +31 -0
- sandloom/shared/authz/context.py +89 -0
- sandloom/shared/authz/deps.py +287 -0
- sandloom/shared/authz/enforce.py +134 -0
- sandloom/shared/authz/facts.py +600 -0
- sandloom/shared/authz/facts_contract.py +108 -0
- sandloom/shared/authz/live_contracts.py +175 -0
- sandloom/shared/authz/metrics.py +35 -0
- sandloom/shared/authz/projection.py +83 -0
- sandloom/shared/authz/results.py +205 -0
- sandloom/shared/contracts/__init__.py +1 -0
- sandloom/shared/contracts/billing_credits_v1.py +56 -0
- sandloom/shared/contracts/billing_entitlements_v1.py +54 -0
- sandloom/shared/contracts/identity_contact_v1.py +38 -0
- sandloom/shared/contracts/identity_dto.py +32 -0
- sandloom/shared/contracts/identity_security_v1.py +34 -0
- sandloom/shared/contracts/tenancy_dto.py +41 -0
- sandloom/shared/contracts/tenancy_membership_v1.py +69 -0
- sandloom/shared/events/billing.credits.added.v1.json +51 -0
- sandloom/shared/events/billing.credits.restored.v1.json +51 -0
- sandloom/shared/events/billing.credits.reversed.v1.json +51 -0
- sandloom/shared/events/billing.credits.spent.v1.json +51 -0
- sandloom/shared/events/billing.subscription.canceled.v1.json +51 -0
- sandloom/shared/events/billing.subscription.created.v1.json +51 -0
- sandloom/shared/events/billing.subscription.updated.v1.json +51 -0
- sandloom/shared/events/identity.sso_linked.v1.json +86 -0
- sandloom/shared/events/identity.sso_unlinked.v1.json +86 -0
- sandloom/shared/events/identity.twofa_backup_codes_regenerated.v1.json +86 -0
- sandloom/shared/events/identity.twofa_disabled.v1.json +86 -0
- sandloom/shared/events/identity.twofa_enabled.v1.json +86 -0
- sandloom/shared/events/identity.user_deleted.v1.json +86 -0
- sandloom/shared/events/identity.user_email_confirmed.v1.json +86 -0
- sandloom/shared/events/identity.user_logged_in.v1.json +86 -0
- sandloom/shared/events/identity.user_logged_out.v1.json +86 -0
- sandloom/shared/events/identity.user_password_reset.v1.json +86 -0
- sandloom/shared/events/identity.user_registered.v1.json +86 -0
- sandloom/shared/events/identity.user_role_assigned.v1.json +86 -0
- sandloom/shared/events/identity.user_role_revoked.v1.json +86 -0
- sandloom/shared/events/identity.user_sessions_revoked.v1.json +86 -0
- sandloom/shared/events/identity.user_updated.v1.json +86 -0
- sandloom/shared/events/tenancy.invitation_accepted.v1.json +48 -0
- sandloom/shared/events/tenancy.invitation_created.v1.json +48 -0
- sandloom/shared/events/tenancy.invitation_revoked.v1.json +48 -0
- sandloom/shared/events/tenancy.member_added.v1.json +62 -0
- sandloom/shared/events/tenancy.member_added.v2.json +66 -0
- sandloom/shared/events/tenancy.member_removed.v1.json +62 -0
- sandloom/shared/events/tenancy.member_removed.v2.json +66 -0
- sandloom/shared/events/tenancy.member_role_changed.v1.json +62 -0
- sandloom/shared/events/tenancy.member_role_changed.v2.json +66 -0
- sandloom/shared/events/tenancy.organization_created.v1.json +29 -0
- sandloom/shared/events/tenancy.organization_deleted.v1.json +29 -0
- sandloom/shared/events/tenancy.organization_updated.v1.json +29 -0
- sandloom/shared/guards/__init__.py +0 -0
- sandloom/shared/guards/auth.py +26 -0
- sandloom/shared/guards/platform.py +19 -0
- sandloom/shared/guards/service.py +27 -0
- sandloom/shared/membership.py +72 -0
- sandloom/shared/subject.py +122 -0
- sandloom-0.7.0a1.dist-info/METADATA +97 -0
- sandloom-0.7.0a1.dist-info/RECORD +498 -0
- sandloom-0.7.0a1.dist-info/WHEEL +4 -0
- sandloom-0.7.0a1.dist-info/entry_points.txt +2 -0
- sandloom-0.7.0a1.dist-info/licenses/LICENSE +202 -0
- sandloom-0.7.0a1.dist-info/licenses/NOTICE +8 -0
sandloom/__init__.py
ADDED
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
"""Sandloom framework — top-level CLI (`sandloom`).
|
|
2
|
+
|
|
3
|
+
Subcommands:
|
|
4
|
+
sandloom new <app> scaffold a standalone application that consumes the
|
|
5
|
+
framework (see sandloom.core.cli.project)
|
|
6
|
+
sandloom add ... generate code: a module, an event, a contract, a
|
|
7
|
+
consumer, a saga, a projection, a task, and a
|
|
8
|
+
module's microservices deployment (sandloom add deploy)
|
|
9
|
+
(see sandloom.core.cli.add)
|
|
10
|
+
sandloom check run the architecture (module isolation) rules against
|
|
11
|
+
./architecture_rules.yml (see sandloom.core.cli.check)
|
|
12
|
+
sandloom explain <code> the long form of a framework error code (SANDLOOM-xxxx)
|
|
13
|
+
sandloom docs <name> the Public API 1.0 reference of a name or module
|
|
14
|
+
(sandloom.sdk; see sandloom.sdk.tooling.docs_main)
|
|
15
|
+
sandloom generate [module ...]
|
|
16
|
+
write every generated file (module, route and
|
|
17
|
+
contract snapshots, contract stubs, DTO copies,
|
|
18
|
+
exported event schemas) after the compatibility
|
|
19
|
+
checks (see sandloom.core.cli.generated)
|
|
20
|
+
sandloom test [module] the module's tests, the fast (--full: whole) parallel
|
|
21
|
+
suite and every static gate, with one summary; it
|
|
22
|
+
never writes a generated file (see
|
|
23
|
+
sandloom.core.cli.run_tests)
|
|
24
|
+
sandloom migrate ... database migrations (see sandloom.core.cli.migrate);
|
|
25
|
+
`sandloom migrate new <module> "<msg>"` autogenerates a
|
|
26
|
+
revision with row-level security
|
|
27
|
+
sandloom projection ... operate query projections (see
|
|
28
|
+
sandloom.core.cli.projections)
|
|
29
|
+
sandloom outbox ... list / requeue dead-lettered outbox events
|
|
30
|
+
sandloom streams ... list / replay the Streams dead-letter queue
|
|
31
|
+
(both: see sandloom.core.cli.events)
|
|
32
|
+
sandloom keys generate generate an asymmetric signing key pair (JWT
|
|
33
|
+
access tokens, or --purpose rpc: a service identity)
|
|
34
|
+
sandloom keys allowlist derive RPC_ALLOWED_CALLS from SERVICE_BINDINGS
|
|
35
|
+
(both: see sandloom.core.cli.keys)
|
|
36
|
+
sandloom contracts ... sync-contract snapshots + rolling-upgrade compatibility
|
|
37
|
+
checks (see sandloom.core.cli.contracts)
|
|
38
|
+
sandloom routes ... per-module route snapshots (method, path, operation
|
|
39
|
+
class) and the route reference (sandloom.core.cli.routes)
|
|
40
|
+
sandloom admin export export the platform-owner UI manifest
|
|
41
|
+
sandloom backup ... backup plan, restore verification, security-cache
|
|
42
|
+
reconciliation after a restore (see sandloom.core.cli.backup)
|
|
43
|
+
sandloom sagas ... list / show / retry / park / resolve saga instances
|
|
44
|
+
(see sandloom.core.cli.sagas)
|
|
45
|
+
sandloom security ... incident response: mass session revocation, forced
|
|
46
|
+
password reset, audit export (see sandloom.core.cli.security)
|
|
47
|
+
sandloom config dump the effective settings, secrets redacted, with the
|
|
48
|
+
source of each value (see sandloom.core.cli.config)
|
|
49
|
+
sandloom doctor read-only deployment preflight: config, modules,
|
|
50
|
+
infra reachability, migration heads, consumer lag,
|
|
51
|
+
RLS (see sandloom.core.cli.doctor)
|
|
52
|
+
sandloom version print the installed framework version
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
from __future__ import annotations
|
|
56
|
+
|
|
57
|
+
import argparse
|
|
58
|
+
import importlib
|
|
59
|
+
import sys
|
|
60
|
+
from pathlib import Path
|
|
61
|
+
from typing import Any
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _static_import(name: str) -> Any:
|
|
65
|
+
"""Import a STATIC CLI module (``sandloom new`` / ``add`` / ``check``).
|
|
66
|
+
|
|
67
|
+
``sandloom.core`` resolves its re-exports lazily, so these code-generation and
|
|
68
|
+
static-analysis commands never build the settings object and work in an
|
|
69
|
+
empty directory with no DATABASE_URL / JWT_SECRET configured.
|
|
70
|
+
"""
|
|
71
|
+
return importlib.import_module(name)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
#: Commands that read the deployment's configuration: they refuse to run on
|
|
75
|
+
#: one a process would refuse to boot with, like the app and the worker.
|
|
76
|
+
#: (``migrate`` checks in its own entry point, ``sandloom.core.cli.migrate``; ``doctor``
|
|
77
|
+
#: reports the problems instead.)
|
|
78
|
+
_CONFIGURED_COMMANDS = frozenset(
|
|
79
|
+
{
|
|
80
|
+
"projection",
|
|
81
|
+
"outbox",
|
|
82
|
+
"streams",
|
|
83
|
+
"contracts",
|
|
84
|
+
"routes",
|
|
85
|
+
"backup",
|
|
86
|
+
"security",
|
|
87
|
+
"config",
|
|
88
|
+
"sagas",
|
|
89
|
+
}
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _load_test_env_for_authoring() -> None:
|
|
94
|
+
"""``sandloom migrate new`` and ``sandloom generate`` run where ``sandloom
|
|
95
|
+
test`` runs: with the project's ``.env.test`` (+ ``SANDLOOM_TEST_*``)
|
|
96
|
+
loaded, like the test harness, before the settings object is built.
|
|
97
|
+
``migrate new`` writes only to a scratch database on that server, never
|
|
98
|
+
to the configured ones; ``generate`` connects to none."""
|
|
99
|
+
try:
|
|
100
|
+
fixtures = _static_import("sandloom.core.testing.env")
|
|
101
|
+
except ImportError: # no test tooling installed: the process env stands
|
|
102
|
+
return
|
|
103
|
+
if fixtures.find_env_file([Path.cwd()]) is not None:
|
|
104
|
+
fixtures.load_test_env([Path.cwd()])
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _enforce_configuration() -> None:
|
|
108
|
+
"""The boot checks of ``create_app`` (``SystemExit`` with the reason)."""
|
|
109
|
+
# Imported here: the static commands (new / add / check / keys /
|
|
110
|
+
# admin) must not build the settings object.
|
|
111
|
+
from sandloom.core.app_factory import enforce_configuration
|
|
112
|
+
|
|
113
|
+
enforce_configuration()
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _version() -> str:
|
|
117
|
+
try:
|
|
118
|
+
from importlib.metadata import version
|
|
119
|
+
|
|
120
|
+
return version("sandloom")
|
|
121
|
+
except Exception: # pragma: no cover # noqa: BLE001 - editable / unbuilt tree has no dist metadata
|
|
122
|
+
return "0.0.0+local"
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _cmd_new(argv: list[str]) -> int:
|
|
126
|
+
project = _static_import("sandloom.core.cli.project")
|
|
127
|
+
generate_project, quickstart = project.generate_project, project.quickstart
|
|
128
|
+
|
|
129
|
+
parser = argparse.ArgumentParser(
|
|
130
|
+
prog="sandloom new", description="Scaffold a standalone Sandloom application"
|
|
131
|
+
)
|
|
132
|
+
parser.add_argument("app", help="application name (snake_case, e.g. helpdesk)")
|
|
133
|
+
parser.add_argument(
|
|
134
|
+
"--dir", type=Path, default=Path.cwd(), help="parent directory (default: cwd)"
|
|
135
|
+
)
|
|
136
|
+
parser.add_argument(
|
|
137
|
+
"--with",
|
|
138
|
+
dest="batteries",
|
|
139
|
+
default="",
|
|
140
|
+
help="comma-separated standard modules to install and load: "
|
|
141
|
+
"identity,tenancy,billing (the sandloom-<module> packages)",
|
|
142
|
+
)
|
|
143
|
+
parser.add_argument(
|
|
144
|
+
"--no-batteries",
|
|
145
|
+
action="store_true",
|
|
146
|
+
help="install no standard module (minimal app)",
|
|
147
|
+
)
|
|
148
|
+
parser.add_argument(
|
|
149
|
+
"--module",
|
|
150
|
+
default="example",
|
|
151
|
+
help="name of the initial sample module (default: example)",
|
|
152
|
+
)
|
|
153
|
+
parser.add_argument(
|
|
154
|
+
"--framework-req",
|
|
155
|
+
default=None,
|
|
156
|
+
help=(
|
|
157
|
+
"override the framework dependency requirement string "
|
|
158
|
+
"(default: sandloom[redis,celery]>=0.7.0a1,<0.8; each --with module "
|
|
159
|
+
"adds its sandloom-<module> package)"
|
|
160
|
+
),
|
|
161
|
+
)
|
|
162
|
+
parser.add_argument(
|
|
163
|
+
"--framework-source",
|
|
164
|
+
choices=("pypi", "git", "path"),
|
|
165
|
+
default=None,
|
|
166
|
+
help="distribution source (checkout: git; installed wheel: pypi)",
|
|
167
|
+
)
|
|
168
|
+
parser.add_argument(
|
|
169
|
+
"--framework-path",
|
|
170
|
+
type=Path,
|
|
171
|
+
default=None,
|
|
172
|
+
help=(
|
|
173
|
+
"framework repository (or its backend/ directory, holding "
|
|
174
|
+
"packages/) for --framework-source path"
|
|
175
|
+
),
|
|
176
|
+
)
|
|
177
|
+
args = parser.parse_args(argv)
|
|
178
|
+
|
|
179
|
+
batteries: list[str] = []
|
|
180
|
+
if not args.no_batteries and args.batteries:
|
|
181
|
+
batteries = [m.strip() for m in args.batteries.split(",") if m.strip()]
|
|
182
|
+
|
|
183
|
+
try:
|
|
184
|
+
created = generate_project(
|
|
185
|
+
args.app,
|
|
186
|
+
args.dir,
|
|
187
|
+
with_batteries=batteries,
|
|
188
|
+
sample_module=args.module,
|
|
189
|
+
framework_req=args.framework_req,
|
|
190
|
+
framework_source=args.framework_source,
|
|
191
|
+
framework_path=args.framework_path,
|
|
192
|
+
)
|
|
193
|
+
except (ValueError, FileExistsError) as exc:
|
|
194
|
+
print(f"error: {exc}", file=sys.stderr)
|
|
195
|
+
return 1
|
|
196
|
+
|
|
197
|
+
root = args.dir / args.app
|
|
198
|
+
print(f"Created application '{args.app}' ({len(created)} files) at {root}")
|
|
199
|
+
# The generated files (snapshots, schemas, stubs): the app's own CI gate
|
|
200
|
+
# (`sandloom test --ci`) only checks them, so a fresh app must carry them.
|
|
201
|
+
problem = project.write_generated_files(root)
|
|
202
|
+
if problem is not None:
|
|
203
|
+
print(
|
|
204
|
+
f"note: generated files not written ({problem}); "
|
|
205
|
+
"run `uv run sandloom generate` once the app installs"
|
|
206
|
+
)
|
|
207
|
+
# The quickstart's one source (sandloom.core.cli.project.QUICKSTART): the docs
|
|
208
|
+
# are tested against it and the CI job `quickstart` runs these lines.
|
|
209
|
+
in_cwd = args.dir.resolve() == Path.cwd().resolve()
|
|
210
|
+
lines = quickstart(args.app, args.module, path=None if in_cwd else str(root))
|
|
211
|
+
print("\nNext steps:\n" + "".join(f" {line}\n" for line in lines))
|
|
212
|
+
return 0
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def main() -> None: # noqa: C901
|
|
216
|
+
parser = argparse.ArgumentParser(
|
|
217
|
+
prog="sandloom", description="Sandloom framework CLI"
|
|
218
|
+
)
|
|
219
|
+
sub = parser.add_subparsers(dest="command")
|
|
220
|
+
sub.add_parser("new", add_help=False, help="scaffold a standalone application")
|
|
221
|
+
sub.add_parser(
|
|
222
|
+
"add",
|
|
223
|
+
add_help=False,
|
|
224
|
+
help="generate code: module, event, contract, consumer, saga, "
|
|
225
|
+
"projection, task, deploy",
|
|
226
|
+
)
|
|
227
|
+
sub.add_parser(
|
|
228
|
+
"check", add_help=False, help="run architecture (module isolation) checks"
|
|
229
|
+
)
|
|
230
|
+
sub.add_parser(
|
|
231
|
+
"explain", add_help=False, help="explain an SANDLOOM-xxxx error code"
|
|
232
|
+
)
|
|
233
|
+
sub.add_parser(
|
|
234
|
+
"docs", add_help=False, help="the sandloom.sdk reference: sandloom docs <name>"
|
|
235
|
+
)
|
|
236
|
+
sub.add_parser(
|
|
237
|
+
"generate",
|
|
238
|
+
add_help=False,
|
|
239
|
+
help="write the generated files (snapshots, stubs, DTO copies, schemas)",
|
|
240
|
+
)
|
|
241
|
+
sub.add_parser(
|
|
242
|
+
"test", add_help=False, help="module tests + fast suite + static gates"
|
|
243
|
+
)
|
|
244
|
+
sub.add_parser("migrate", add_help=False, help="run database migrations")
|
|
245
|
+
sub.add_parser("projection", add_help=False, help="operate query projections")
|
|
246
|
+
sub.add_parser("outbox", add_help=False, help="requeue dead-lettered outbox events")
|
|
247
|
+
sub.add_parser(
|
|
248
|
+
"streams", add_help=False, help="replay the Streams dead-letter queue"
|
|
249
|
+
)
|
|
250
|
+
sub.add_parser("keys", add_help=False, help="generate signing keys")
|
|
251
|
+
sub.add_parser(
|
|
252
|
+
"contracts",
|
|
253
|
+
add_help=False,
|
|
254
|
+
help="contract snapshots / compatibility checks",
|
|
255
|
+
)
|
|
256
|
+
sub.add_parser(
|
|
257
|
+
"routes", add_help=False, help="route snapshots (each route's policy)"
|
|
258
|
+
)
|
|
259
|
+
sub.add_parser("admin", add_help=False, help="export a generated admin UI manifest")
|
|
260
|
+
sub.add_parser("backup", add_help=False, help="backup plan / restore verification")
|
|
261
|
+
sub.add_parser(
|
|
262
|
+
"security", add_help=False, help="incident response (sessions, audit export)"
|
|
263
|
+
)
|
|
264
|
+
sub.add_parser(
|
|
265
|
+
"sagas", add_help=False, help="list / show / retry / park / resolve sagas"
|
|
266
|
+
)
|
|
267
|
+
sub.add_parser(
|
|
268
|
+
"config", add_help=False, help="effective settings (sandloom config dump)"
|
|
269
|
+
)
|
|
270
|
+
sub.add_parser("doctor", add_help=False, help="read-only deployment preflight")
|
|
271
|
+
sub.add_parser("version", help="print the framework version")
|
|
272
|
+
|
|
273
|
+
args, rest = parser.parse_known_args()
|
|
274
|
+
if args.command in _CONFIGURED_COMMANDS:
|
|
275
|
+
_enforce_configuration()
|
|
276
|
+
|
|
277
|
+
if args.command == "new":
|
|
278
|
+
raise SystemExit(_cmd_new(rest))
|
|
279
|
+
if args.command == "add":
|
|
280
|
+
raise SystemExit(_static_import("sandloom.core.cli.add").main(rest))
|
|
281
|
+
if args.command == "check":
|
|
282
|
+
raise SystemExit(_static_import("sandloom.core.cli.check").main(rest))
|
|
283
|
+
if args.command == "generate":
|
|
284
|
+
_load_test_env_for_authoring()
|
|
285
|
+
raise SystemExit(_static_import("sandloom.core.cli.generated").main(rest))
|
|
286
|
+
if args.command == "test":
|
|
287
|
+
raise SystemExit(_static_import("sandloom.core.cli.run_tests").main(rest))
|
|
288
|
+
if args.command == "docs":
|
|
289
|
+
raise SystemExit(_static_import("sandloom.sdk.tooling").docs_main(rest))
|
|
290
|
+
if args.command == "explain":
|
|
291
|
+
raise SystemExit(_static_import("sandloom.core.cli.explain").main(rest))
|
|
292
|
+
if args.command == "migrate":
|
|
293
|
+
if rest[:1] == ["new"]:
|
|
294
|
+
_load_test_env_for_authoring()
|
|
295
|
+
from sandloom.core.cli.migrate import main as migrate_main
|
|
296
|
+
|
|
297
|
+
raise SystemExit(migrate_main(rest))
|
|
298
|
+
if args.command == "projection":
|
|
299
|
+
from sandloom.core.cli.projections import main as projection_main
|
|
300
|
+
|
|
301
|
+
raise SystemExit(projection_main(rest))
|
|
302
|
+
if args.command == "outbox":
|
|
303
|
+
from sandloom.core.cli.events import outbox_main
|
|
304
|
+
|
|
305
|
+
raise SystemExit(outbox_main(rest))
|
|
306
|
+
if args.command == "streams":
|
|
307
|
+
from sandloom.core.cli.events import streams_main
|
|
308
|
+
|
|
309
|
+
raise SystemExit(streams_main(rest))
|
|
310
|
+
if args.command == "keys":
|
|
311
|
+
raise SystemExit(_static_import("sandloom.core.cli.keys").main(rest))
|
|
312
|
+
if args.command == "contracts":
|
|
313
|
+
from sandloom.core.cli.contracts import main as contracts_main
|
|
314
|
+
|
|
315
|
+
raise SystemExit(contracts_main(rest))
|
|
316
|
+
if args.command == "routes":
|
|
317
|
+
from sandloom.core.cli.routes import main as routes_main
|
|
318
|
+
|
|
319
|
+
raise SystemExit(routes_main(rest))
|
|
320
|
+
if args.command == "admin":
|
|
321
|
+
raise SystemExit(_static_import("sandloom.core.cli.admin").main(rest))
|
|
322
|
+
if args.command == "backup":
|
|
323
|
+
from sandloom.core.cli.backup import main as backup_main
|
|
324
|
+
|
|
325
|
+
raise SystemExit(backup_main(rest))
|
|
326
|
+
if args.command == "security":
|
|
327
|
+
from sandloom.core.cli.security import main as security_main
|
|
328
|
+
|
|
329
|
+
raise SystemExit(security_main(rest))
|
|
330
|
+
if args.command == "sagas":
|
|
331
|
+
raise SystemExit(_static_import("sandloom.core.cli.sagas").main(rest))
|
|
332
|
+
if args.command == "config":
|
|
333
|
+
from sandloom.core.cli.config import main as config_main
|
|
334
|
+
|
|
335
|
+
raise SystemExit(config_main(rest))
|
|
336
|
+
if args.command == "doctor":
|
|
337
|
+
from sandloom.core.cli.doctor import main as doctor_main
|
|
338
|
+
|
|
339
|
+
raise SystemExit(doctor_main(rest))
|
|
340
|
+
if args.command == "version":
|
|
341
|
+
print(_version())
|
|
342
|
+
raise SystemExit(0)
|
|
343
|
+
|
|
344
|
+
parser.print_help()
|
|
345
|
+
raise SystemExit(0)
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
if __name__ == "__main__": # pragma: no cover
|
|
349
|
+
main()
|
sandloom/core/AGENTS.md
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Sandloom kernel-contributor contract (`sandloom.core`, `sandloom.sdk`, `sandloom.shared`)
|
|
2
|
+
|
|
3
|
+
For changes to the framework kernel itself. Module authors never need this file: their
|
|
4
|
+
contract is `src/sandloom/AGENTS.md`. The module rules still apply here wherever kernel code
|
|
5
|
+
acts like a module (units, effects, tenancy). Concepts: `docs/concepts/index.md`; every check
|
|
6
|
+
and refusal: `docs/reference/error-codes.md` (`sandloom.core.error_codes` is its source).
|
|
7
|
+
|
|
8
|
+
## Layers and imports (ADR-0007)
|
|
9
|
+
|
|
10
|
+
- **Layers.** `sandloom.core` is layered top (tooling, composition) to bottom
|
|
11
|
+
(configuration): `.importlinter`, checked by `lint-imports` and
|
|
12
|
+
`tests/architecture/test_kernel_import_contracts.py`.
|
|
13
|
+
- A module imports its own layer or a lower one, with no cycle at any depth.
|
|
14
|
+
- `sandloom.core.config` is a leaf and imports nothing above it.
|
|
15
|
+
- `exhaustive`: a new `sandloom.core` child fails until you place it in a layer.
|
|
16
|
+
- No `ignore_imports`: one would be debt needing a `; reason:` and an owner.
|
|
17
|
+
- **Function-local imports.** A kernel `# noqa: PLC0415` states its category:
|
|
18
|
+
- `- optional: <reason>`: the dependency may be absent or unconfigured;
|
|
19
|
+
- `- cold: <reason>`: import cost or side effects kept off the app import.
|
|
20
|
+
|
|
21
|
+
The reason names a boundary (plugin entry, static command, gunicorn master,
|
|
22
|
+
worker healthcheck, a driver SDK on the app path); a cycle break is not a
|
|
23
|
+
category. A hoisted import is `import sandloom.core.x as _x` so test patches still
|
|
24
|
+
apply. Check: `test_lint_suppression_ratchet.py`.
|
|
25
|
+
- **Other `# noqa` markers:** one code per line (`PGH004`, `RUF100`); `BLE001`
|
|
26
|
+
and bandit `S…` need a reason after ` - `; `NOQA_BASELINE` only goes down
|
|
27
|
+
(`docs/contributing/lint-policy.md`).
|
|
28
|
+
- **`sandloom.sdk` is the only public surface** (Public API 1.0, ADR-0010). Each
|
|
29
|
+
public module declares `__all__` and `__beginner__`; the root re-exports
|
|
30
|
+
the 29 beginner names. `public_api_baseline.json` records every
|
|
31
|
+
name and signature (SANDLOOM-T008), and each module's generated reference block
|
|
32
|
+
stays current (`sandloom docs --write`). Adding a name is an API decision.
|
|
33
|
+
- **Levels:** public facades > `sandloom.sdk._decl` (L1, declarative) >
|
|
34
|
+
`sandloom.sdk._prim` (L2 primitives) > `sandloom.core` (L3). `_decl` never imports
|
|
35
|
+
`sandloom.core`; `sandloom.core` and `sandloom.shared` never import `sandloom.sdk`; every L2
|
|
36
|
+
name L1 uses is public (`test_l1_uses_only_public_l2`).
|
|
37
|
+
- **Importing `sandloom.sdk` reads no environment and does no I/O**
|
|
38
|
+
(`test_sdk_import_is_side_effect_free`): settings stay lazy.
|
|
39
|
+
- The framework is unreleased: remove a name outright, no compat aliases.
|
|
40
|
+
|
|
41
|
+
## Guarantees and effects (ADR-0005)
|
|
42
|
+
|
|
43
|
+
- **The effect model.** Every write-side guarantee is one model: outbox,
|
|
44
|
+
durable inbox, command dedupe, `idempotency_guard` (cache and durable),
|
|
45
|
+
enqueue dedupe, `on_commit` / `before_commit`. See
|
|
46
|
+
`docs/adr/0005-effect-model.md`, `sandloom.core.effects` and `COMMIT_PIPELINE` in
|
|
47
|
+
`sandloom.core.unit_of_work`.
|
|
48
|
+
- **Do not add a new dedupe store or a new post-commit variant.** Reuse one,
|
|
49
|
+
or amend the ADR. Review enforces this; no check can.
|
|
50
|
+
- **Guarantee windows are startup-checked** (`sandloom.core.guarantee_windows`,
|
|
51
|
+
stable risk ids). The command TTL must cover the relay horizon, and
|
|
52
|
+
`--inbox-days` must cover stream retention.
|
|
53
|
+
- **The core chain is infra-only**: outbox, audit, consumer_inbox and
|
|
54
|
+
contract_command_log (`migrations/core/versions/`, shipped as
|
|
55
|
+
`sandloom/core/migrations/core_chain`). Module tables never go there.
|
|
56
|
+
|
|
57
|
+
## Configuration (ADR-0006, configuration tiers)
|
|
58
|
+
|
|
59
|
+
- **Classify every new setting** in `sandloom.core.config.tiers` as semantic or
|
|
60
|
+
ops. Check: `src/sandloom/core/tests/test_config_tiers.py`.
|
|
61
|
+
- The semantic count is ratcheted (ceiling 16) and needs an ADR to grow.
|
|
62
|
+
Prefer an ops knob or a profile-chosen value.
|
|
63
|
+
- **A production weakening is an accepted risk, never a boolean.** Add an id
|
|
64
|
+
to `sandloom.core.config.accepted_risks` and read it with
|
|
65
|
+
`settings.accepts_risk(id)`. An unknown id fails startup.
|
|
66
|
+
- **Removed settings** (`config_tiers.REMOVED`) fail startup unless they are
|
|
67
|
+
set to their inert value.
|
|
68
|
+
- **Read configuration only through `Settings`, never `os.getenv`.** The
|
|
69
|
+
exceptions are `SANDLOOM_COMPOSITION_ROOT` (process env first) and
|
|
70
|
+
`SANDLOOM_WORKER_TASKQUEUE`.
|
|
71
|
+
|
|
72
|
+
## Infrastructure layer
|
|
73
|
+
|
|
74
|
+
- **Drivers construct backends.** A backend constructor
|
|
75
|
+
(`create_async_engine`, `redis.from_url`, `Celery(...)`, `Storage(...)`)
|
|
76
|
+
appears only in `sandloom.core.drivers/**`, built lazily by `get_default_*()`
|
|
77
|
+
factories. Check: `test_infra_constructed_only_in_drivers`.
|
|
78
|
+
- **SQLAlchemy stays inside the relational surface**: `orm`, `tenant`, `di`,
|
|
79
|
+
`sql_alchemy/`, `projections/upsert`, `migrations/` and the drivers.
|
|
80
|
+
`TYPE_CHECKING` imports are exempt. Check: `test_relational_paradigm_boundary`.
|
|
81
|
+
- **Outbox and audit writes go through the `OutboxStore` / `AuditStore`
|
|
82
|
+
contracts** (`provider.outbox()` / `.audit()`). `sandloom.core.di` never imports
|
|
83
|
+
a concrete ORM model.
|
|
84
|
+
- **New capabilities ship as contracts only.** Register a `CapabilitySpec`
|
|
85
|
+
with `stability="experimental"`; a driver plugin supplies the backend.
|
|
86
|
+
|
|
87
|
+
## Kernel conventions
|
|
88
|
+
|
|
89
|
+
- **The kernel names no module.** Module names come only from `sandloom.core.descriptors.module_names`
|
|
90
|
+
(entry-point name, else the last import segment; an ambiguous name: SANDLOOM-B020).
|
|
91
|
+
- **Kernel code reads a request's bearer only through
|
|
92
|
+
`sandloom.core.auth.bearer.bearer_claims(request)`**, which returns access
|
|
93
|
+
tokens only.
|
|
94
|
+
- **Route policy is model E** (ADR-0009, `sandloom.core.route_policy`): deny by
|
|
95
|
+
default, everything else derived. The declarations a route may carry
|
|
96
|
+
(`public`, `no_idempotency`, `replay_safe`, `sensitive`, `operation_intent`,
|
|
97
|
+
`writes`, `allow_multi_db_write`) are no-op markers that `create_app` prunes
|
|
98
|
+
from `route.dependant`; `resolve_route_policy` reads them through
|
|
99
|
+
`sandloom.core.route_markers.route_marker_calls`.
|
|
100
|
+
- **Startup refusals belong in `create_app` / `enforce_configuration`**, which
|
|
101
|
+
every entry point runs (app, worker, `sandloom migrate`, the `sandloom` CLI). Each
|
|
102
|
+
refusal has an `sandloom.core.error_codes` entry and says what to change.
|
|
103
|
+
- **The framework carries no deprecated API.** `error::DeprecationWarning:sandloom`
|
|
104
|
+
turns one into a test failure.
|
|
105
|
+
- **Hot paths are measured.** Change the request path, the UoW or eventing
|
|
106
|
+
only with numbers: cachegrind instruction counts on a shared machine
|
|
107
|
+
(`benchmarks/`, `docs/design/*profile*`).
|
|
108
|
+
- **The test harness is framework code** (`sandloom.core.testing`, public through
|
|
109
|
+
`sandloom.sdk.testing`). A seam module tests need goes there.
|
|
110
|
+
|
|
111
|
+
## Before you push
|
|
112
|
+
|
|
113
|
+
- `uv run sandloom generate`, `uv run sandloom test --full`, then `uv run sandloom test --ci`
|
|
114
|
+
(no ruff fixes) and `uv run python tools/checks/check_architecture.py`, plus:
|
|
115
|
+
- the slow suites: `SANDLOOM_TEST_REDIS_DB_STRIDE=auto uv run pytest -q -n auto --dist loadfile`
|
|
116
|
+
(split conformance included; `sandloom test` will wrap it).
|
|
117
|
+
- Run the local CI stand-in from the repo root:
|
|
118
|
+
`tools/ci/ci_local.sh <ref> [--jobs a,b]` (`docs/contributing/local-ci.md`).
|
|
119
|
+
- On a shared machine, use your own test DB and Redis (`SANDLOOM_TEST_*`), never
|
|
120
|
+
`pkill` by pattern, and measure CPU only when the machine is idle.
|
sandloom/core/CLAUDE.md
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@AGENTS.md
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""The Sandloom kernel.
|
|
2
|
+
|
|
3
|
+
The package exports nothing: import the submodule that owns a name.
|
|
4
|
+
Business modules use the public core API only (``sandloom.core.di``,
|
|
5
|
+
``sandloom.core.facade``, ``sandloom.core.module_api``, ``sandloom.core.descriptors``,
|
|
6
|
+
``sandloom.core.orm``, ``sandloom.core.projections``); infrastructure is reached through
|
|
7
|
+
``sandloom.core.di`` and the capability registry — never via concrete-backend
|
|
8
|
+
globals. Importing a submodule costs only that submodule, so the static tools
|
|
9
|
+
(``sandloom add``, ``sandloom new``, ``sandloom check``) never build ``settings``.
|
|
10
|
+
"""
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
"""Framework-internal core modules — not a public API surface.
|
|
2
|
+
|
|
3
|
+
Nothing here is importable by business modules (an architecture test enforces
|
|
4
|
+
it). These modules exist for the composition root and for tests that override
|
|
5
|
+
raw dependencies via ``app.dependency_overrides``.
|
|
6
|
+
"""
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""Default-database raw request dependency (framework-internal).
|
|
2
|
+
|
|
3
|
+
``get_db`` is the raw session provider the request UoW wraps. It lives under
|
|
4
|
+
``sandloom.core._internal`` deliberately: it is NOT a public surface. Only the
|
|
5
|
+
composition root (``create_app``) and test conftests touch it — the latter to
|
|
6
|
+
override it via ``app.dependency_overrides``. The engine/sessionmaker it uses
|
|
7
|
+
are owned and constructed by the database DRIVER
|
|
8
|
+
(``sandloom.core.drivers.sqlalchemy_database``); this module holds no engine of
|
|
9
|
+
its own. Business modules use ``DbSession`` from ``sandloom.core.di`` instead.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from collections.abc import AsyncGenerator
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
from sqlalchemy.ext.asyncio import AsyncSession
|
|
16
|
+
|
|
17
|
+
from sandloom.core.drivers.sqlalchemy_database import (
|
|
18
|
+
build_disposable_engine,
|
|
19
|
+
get_default_sessionmaker,
|
|
20
|
+
release_default_pools,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
async def get_db() -> AsyncGenerator[AsyncSession, None]:
|
|
25
|
+
async with get_default_sessionmaker()() as session:
|
|
26
|
+
yield session
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def is_relational_session(value: Any) -> bool:
|
|
30
|
+
"""True if ``value`` is a relational (UoW) session instance.
|
|
31
|
+
|
|
32
|
+
Lets paradigm-agnostic kernel code (e.g. the RPC proxy) recognise an
|
|
33
|
+
injected database session without importing SQLAlchemy itself — the
|
|
34
|
+
relational session type stays known only to the relational surface.
|
|
35
|
+
"""
|
|
36
|
+
return isinstance(value, AsyncSession)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def is_relational_session_type(annotation: Any) -> bool:
|
|
40
|
+
"""True if ``annotation`` is the relational session type (see above)."""
|
|
41
|
+
return annotation is AsyncSession
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
# Test-harness seams (``sandloom.core.testing``): the harness reaches the driver's
|
|
45
|
+
# default pools and a caller-owned engine through this adapter, so no other
|
|
46
|
+
# kernel module needs to import a concrete driver.
|
|
47
|
+
__all__ = [
|
|
48
|
+
"build_disposable_engine",
|
|
49
|
+
"get_db",
|
|
50
|
+
"is_relational_session",
|
|
51
|
+
"is_relational_session_type",
|
|
52
|
+
"release_default_pools",
|
|
53
|
+
]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Authenticated operator HTTP surface, separate from internal probes."""
|